NAME
       selection - Manipulate the X selection

SYNOPSIS
       selection option ?arg arg ...?


DESCRIPTION
       This  command  provides a Tcl interface to the X selection
       mechanism and implements the full selection  functionality
       described  in the X Inter-Client Communication Conventions
       Manual (ICCCM).

       The first argument to selection determines the  format  of
       the rest of the arguments and the behavior of the command.
       The following forms are currently supported:


       selection clear ?-displayof window? ?-selection selection?
              If  selection  exists anywhere on window's display,
              clear it so  that  no  window  owns  the  selection
              anymore.   Selection specifies the X selection that
              should be cleared, and should be an atom name  such
              as  PRIMARY  or  CLIPBOARD;  see  the  Inter-Client
              Communication  Conventions  Manual   for   complete
              details.   Selection defaults to PRIMARY and window
              defaults to ``.''.  Returns an empty string.

       selection get ?-displayof window? ?-selection  selection?
       ?-type type?
              Retrieves the  value  of  selection  from  window's
              display  and  returns  it  as  a result.  Selection
              defaults to PRIMARY and window defaults  to  ``.''.
              Type  specifies  the form in which the selection is
              to  be  returned  (the   desired   ``target''   for
              conversion, in ICCCM terminology), and should be an
              atom name such as  STRING  or  FILE_NAME;  see  the
              Inter-Client  Communication  Conventions Manual for
              complete details.  Type defaults  to  STRING.   The
              selection  owner may choose to return the selection
              in any of several different representation formats,
              such as STRING, ATOM, INTEGER, etc. (this format is
              different than the selection type;  see  the  ICCCM
              for  all  the confusing details).  If the selection
              is returned in a non-string format, such as INTEGER
              or  ATOM,  the  selection  command  converts  it to
              string format as a collection of  fields  separated
              by  spaces:  atoms  are  converted to their textual
              names,  and   anything   else   is   converted   to
              hexadecimal integers.

       selection  handle  ?-selection  selection?  ?-type type?
       ?-format format? window command
              Creates a handler for selection requests, such that
              command will  be  executed  whenever  selection  is
              owned by window and someone attempts to retrieve it
              in the form given by type (e.g. type  is  specified
              in  the selection get command).  Selection defaults
              to PRIMARY, type defaults  to  STRING,  and  format
              defaults  to STRING.  If command is an empty string
              then any existing handler  for  window,  type,  and
              selection is removed.

              When   selection   is   requested,  window  is  the
              selection owner, and type is  the  requested  type,
              command  will be executed as a Tcl command with two
              additional  numbers  appended  to  it  (with  space
              separators).  The two additional numbers are offset
              and  maxChars:    offset   specifies   a   starting
              character  position  in  the selection and maxChars
              gives the maximum number of characters to retrieve.
              The  command should return a value consisting of at
              most  maxChars  of  the  selection,   starting   at
              position offset.  For very large selections (larger
              than maxChars)  the  selection  will  be  retrieved
              using   several   invocations   of   command   with
              increasing offset values.   If  command  returns  a
              string  whose  length  is  less  than maxChars, the
              return value is  assumed  to  include  all  of  the
              remainder  of  the  selection;   if  the  length of
              command's result is equal to maxChars then  command
              will  be invoked again, until it eventually returns
              a result  shorter  than  maxChars.   The  value  of
              maxChars will always be relatively large (thousands
              of characters).

              If command returns  an  error  then  the  selection
              retrieval  is  rejected  just  as  if the selection
              didn't exist at all.

              The format argument  specifies  the  representation
              that  should  be  used to transmit the selection to
              the requester (the second column of Table 2 of  the
              ICCCM),  and  defaults  to  STRING.   If  format is
              STRING, the selection is transmitted as 8-bit ASCII
              characters  (i.e.   just  in  the  form returned by
              command).  If format is ATOM, then the return value
              from  command  is  divided into fields separated by
              white space;  each field is converted to  its  atom
              value,  and  the  32-bit  atom value is transmitted
              instead of the atom name.  For  any  other  format,
              the  return  value  from  command  is  divided into
              fields separated by white space and each  field  is
              converted   to  a  32-bit  integer;   an  array  of
              integers is transmitted to the selection requester.

              The    format   argument   is   needed   only   for
              compatibility with selection requesters that  don't
              use  Tk.   If  Tk  is  being  used  to retrieve the
              selection then the value is  converted  back  to  a
              string   at   the  requesting  end,  so  format  is
              irrelevant.

       selection own ?-displayof window? ?-selection selection?

       selection own ?-command command? ?-selection selection?
       window
              The  first  form  of selection own returns the path
              name of the window in this  application  that  owns
              selection  on  the display containing window, or an
              empty string if no window in this application  owns
              the  selection.   Selection defaults to PRIMARY and
              window defaults to ``.''.

       The second form of selection own causes window  to  become
       the  new owner of selection on window's display, returning
       an empty string as result. The existing owner, if any,  is
       notified  that  it  has lost the selection.  If command is
       specified, it is a Tcl script to execute when  some  other
       window claims ownership of the selection away from window.
       Selection defaults to PRIMARY.


KEYWORDS
       clear, format, handler,  ICCCM,  own,  selection,  target,
