Manual Pages for UNIX Operating System command usage for man selection

Tk Built-In Commands                                selection(1T)



_________________________________________________________________

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).

     Note that for management of  the  CLIPBOARD  selection  (see
     below), the clipboard command may also be used.

     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



Tk                      Last change: 8.1                        1






Tk Built-In Commands                                selection(1T)



          anything 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 maxChars:  offset  speci-  |
          fies 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 posi-  |
          tion  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 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.




Tk                      Last change: 8.1                        2






Tk Built-In Commands                                selection(1T)



          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.

EXAMPLES
     On X11 platforms, one of the standard  selections  available
     is  the  SECONDARY  selection.  Hardly anything uses it, but
     here is how to read it using Tk:
          set selContents [selection get -selection SECONDARY]

     Many different types of data may be available for  a  selec-
     tion;  the  special type TARGETS allows you to get a list of
     available types:
          foreach type [selection get -type TARGETS] {
             puts "Selection PRIMARY supports type $type"
          }

     To claim the selection, you must first set up a  handler  to
     supply  the  data for the selection.  Then you have to claim
     the selection...
          # Set up the data handler ready for incoming requests
          set foo "This is a string with some data in it... blah blah"
          selection handle -selection SECONDARY . getData
          proc getData {offset maxChars} {
             puts "Retrieving selection starting at $offset"
             return [string range $::foo $offset [expr {$offset+$maxChars}]]
          }

          # Now we grab the selection itself
          puts "Claiming selection"
          selection own -command lost -selection SECONDARY .
          proc lost {} {



Tk                      Last change: 8.1                        3






Tk Built-In Commands                                selection(1T)



             puts "Lost selection"
          }


SEE ALSO
     clipboard(1T)


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

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tk-8   |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tk is available on http://opensolaris.org.






























Tk                      Last change: 8.1                        4