selection(3Tk)

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 sel? ?-type typ? ?-format fmt? 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 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 offset 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 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?
          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    |
          ``.''.

     selection own ?-command command? ?-selection selection? window
          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