tk4.2 User Commands - selection






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  Conven-
          tions  Manual for complete details.  Selection defaults
          to PRIMARY and window defaults to  ``.''.   Returns  an
          empty string.


type?

     selection get ?-displayof window? ?-selection selection? ? -
           type
          Retrieves the value of selection from window's  display
          and returns it as a result.  Selection defaults to PRI-
          MARY and window defaults to ``.''. Type  specifies  the
          form  in  which  the  selection  is to be returned (the
          desired ``target'' for conversion, in  ICCCM  terminol-
          ogy),  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 for-
          mat 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  for-
          mat  as  a  collection  of  fields separated by spaces:
          atoms are converted to their textual  names,  and  any-
          thing else is converted to hexadecimal integers.


format? window command

     selection handle ?-selection selection? ?- type  type?  ?  -
           format
          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 addi-
          tional numbers are offset and maxBytes:  offset  speci-
          fies 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 reques-
          ter (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  transmit-
          ted  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?

     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 noti-
     fied  that  it has lost the selection.  If command is speci-
     fied, it is a Tcl script to execute when some  other  window
     claims  ownership of the selection away from window.  Selec-
     tion defaults to PRIMARY.



KEYWORDS

     clear, format, handler, ICCCM, own, selection, target, type