ABCDEFGHIJKLMNOPQRSTUVWXYZ

selection

selection(n)                 Tk Built-In Commands                 selection(n)



______________________________________________________________________________

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 Communi-
              cation  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  win-
              dow  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  Conven-
              tions  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 tex-
              tual  names, and anything else is converted to hexadecimal inte-
              gers.

       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 win-
              dow, 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 max- |
              Chars:  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 col-
              umn of Table 2 of the ICCCM), and defaults to STRING.  If format
              is STRING, the selection is transmitted as 8-bit  ASCII  charac-
              ters (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 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 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



Tk                                    8.1                         selection(n)