1mNAME0m
       selection - Manipulate the X selection

1mSYNOPSIS0m
       1mselection 4m22moption24m ?4marg24m 4marg24m 4m...24m?


1mDESCRIPTION0m
       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 1mselection 22mdetermines the format of the rest of
       the arguments and the behavior of the command.  The following forms are
       currently supported:


       1mselection clear 22m?1m-displayof 4m22mwindow24m? ?1m-selection 4m22mselection24m?
              If  4mselection24m  exists  anywhere on 4mwindow24m's display, clear it so
              that no window owns the selection anymore.  4mSelection24m  specifies
              the  X  selection  that should be cleared, and should be an atom
              name such as PRIMARY or CLIPBOARD; see the Inter-Client Communi-
              cation  Conventions  Manual  for  complete  details.   4mSelection0m
              defaults to PRIMARY and 4mwindow24m defaults to  ``.''.   Returns  an
              empty string.

       1mselection get 22m?1m-displayof 4m22mwindow24m? ?1m-selection 4m22mselection24m? ?1m-type 4m22mtype24m?
              Retrieves  the  value  of  4mselection24m  from  4mwindow24m's display and
              returns it as a result.  4mSelection24m defaults to PRIMARY and  4mwin-0m
              4mdow24m  defaults  to  ``.''.   4mType24m 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  Conven-
              tions  Manual  for  complete  details.  4mType24m 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
              1mselection  22mcommand  converts it to string format as a collection
              of fields separated by spaces: atoms are converted to their tex-
              tual  names, and anything else is converted to hexadecimal inte-
              gers.

       1mselection handle 22m?1m-selection 4m22mselection24m? ?1m-type 4m22mtype24m?  ?1m-format  4m22mformat24m?
       4mwindow24m 4mcommand0m
              Creates a handler for selection requests, such that 4mcommand24m will
              be  executed  whenever  4mselection24m is owned by 4mwindow24m and someone
              attempts to retrieve it in the form given by 4mtype24m (e.g. 4mtype24m  is
              specified  in the 1mselection get 22mcommand).  4mSelection24m defaults to
              PRIMARY, 4mtype24m defaults to STRING, and 4mformat24m defaults to STRING.
              If 4mcommand24m is an empty string then any existing handler for 4mwin-0m
              4mdow24m, 4mtype24m, and 4mselection24m is removed.

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

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

              The  4mformat24m argument specifies the representation that should be
              used to transmit the selection to the requester (the second col-
              umn of Table 2 of the ICCCM), and defaults to STRING.  If 4mformat0m
              is STRING, the selection is transmitted as 8-bit  ASCII  charac-
              ters (i.e.  just in the form returned by 4mcommand24m).  If 4mformat24m is
              ATOM, then the return value from 4mcommand24m 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 4mformat24m, the return value from 4mcommand0m
              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 4mformat24m argument is needed only for compatibility with selec-
              tion  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 4mformat24m is irrelevant.

       1mselection own 22m?1m-displayof 4m22mwindow24m? ?1m-selection 4m22mselection24m?

       1mselection own 22m?1m-command 4m22mcommand24m? ?1m-selection 4m22mselection24m? 4mwindow0m
              The  first  form  of  1mselection own 22mreturns the path name of the
              window in this application that owns 4mselection24m  on  the  display
              containing  4mwindow24m,  or  an  empty  string  if no window in this
              application owns the selection.  4mSelection24m defaults  to  PRIMARY
              and 4mwindow24m defaults to ``.''.

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


1mKEYWORDS0m
