


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


NAME
       selection - Manipulate the X selection

SYNOPSIS
       (selection option ?arg arg ...?)


DESCRIPTION
       This  procedure  provides  a STk 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 procedure.  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 list.

       (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 ``*root*''.  Type specifies the  form  in  which
              the selection is to be returned (the desired ``target'' for con-
              version, in ICCCM terminology), and should be an atom name  such
              as  STRING or FILE_NAME; see the Inter-Client Communication Con-
              ventions 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 procedure 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 procedure)
              Creates  a  handler  for selection requests, such that procedure
              will be executed whenever selection is owned by window and some-
              one attempts to retrieve it in the form given by type (e.g. type
              is  specified  in  the  selection  get  procedure).    Selection
              defaults  to  PRIMARY,  type  defaults  to  STRING,  and  format
              defaults to STRING.  If procedure is an empty  string  then  any



STk                            3.1                              1





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


              existing handler for window, type, and selection is removed.

              When  selection is requested, window is the selection owner, and
              type is the requested type, procedure will be applied as  a  STk
              procedure  with  a list of two numbers.  The two additional num-
              bers are offset and maxBytes:  offset specifies a starting char-
              acter  position  in the selection and maxBytes gives the maximum
              number of bytes to retrieve.   The  procedure  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 invoca-
              tions of procedure with increasing offset values.  If  procedure
              returns  a string whose length is less than maxBytes, the return
              value is assumed to include all of the remainder of  the  selec-
              tion;   if the length of procedure's result is equal to maxBytes
              then procedure  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 procedure 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 procedure).  If format
              is ATOM, then the return value from procedure  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 pro-
              cedure 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 ?:procedure procedure? ?: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 #f if no window in this application owns
              the selection.   Selection  defaults  to  "PRIMARY"  and  window
              defaults to ``*root*''.
              The second form of selection own causes window to become the new
              owner of selection on window's display, returning an empty  list
              as  result.  The existing owner, if any, is notified that it has
              lost the selection.  If procedure is  specified,  it  is  a  STk
              script to execute when some other window claims ownership of the



STk                            3.1                              2





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


              selection away from window. Selection defaults to "PRIMARY".
























































STk                            3.1                              3


