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  any-
              more.   Selection  specifies  the  X selection that
              should be cleared, and should be an atom name  such
              as  PRIMARY or CLIPBOARD; see the Inter-Client Com-
              munication 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 dis-
              play   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  conver-
              sion,  in ICCCM terminology), and should be an atom
              name such as STRING or FILE_NAME;  see  the  Inter-
              Client  Communication  Conventions  Manual for com-
              plete  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  hexadeci-
              mal 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 selec-
              tion owner, and type is the requested type, command
              will  be  executed  as a Tcl command with two addi-
              tional numbers appended to it (with  space  separa-
              tors).   The  two additional numbers are offset and
              maxBytes:  offset specifies  a  starting  character
              position  in  the  selection and maxBytes gives the
              maximum number of bytes to retrieve.   The  command
              should   return  a  value  consisting  of  at  most
              maxBytes of the  selection,  starting  at  position
              offset.   For  very  large  selections (larger than
              maxBytes) the selection  will  be  retrieved  using
              several invocations of command with increasing off-
              set values.  If  command  returns  a  string  whose
              length  is  less than maxBytes, the return value is
              assumed to include all  of  the  remainder  of  the
              selection;   if  the  length of command's result is
              equal to maxBytes  then  command  will  be  invoked
              again, until it eventually returns a result shorter
              than maxBytes.  The value of maxBytes  will  always
              be relatively large (thousands of bytes).

              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 com-
              mand).   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  inte-
              gers is transmitted to the selection requester.

              The  format argument is needed only for compatibil-
              ity 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,
       type
