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
              maxChars:   offset  specifies  a starting character
              position in the selection and  maxChars  gives  the
              maximum number of characters to retrieve.  The com-
              mand 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 off-
              set  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 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,
