Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

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

       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  selec-tion selection
              tion  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 selec-tion selection
              tion 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,
              UTF8_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.  Note that selection get does not retrieve the selection in
              the UTF8_STRING format unless told to.

       selection handle ?-selection s? ?-type t? ?-format f? window command
              Creates  a  handler for selection requests, such that command will be executed whenever selec-tion selection
              tion s is owned by window and someone attempts to retrieve it in the  form  given  by  type  t
              (e.g.  t  is  specified  in  the selection get command).  S defaults to PRIMARY, t defaults to
              STRING, and f defaults to STRING.  If command is an empty string then any existing handler for
              window,  t,  and  s  is removed.  Note that when the selection is handled as type STRING it is
              also automatically handled as type UTF8_STRING as well.

              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 maxChars:   offset  specifies  a
              starting  character position in the selection and maxChars gives the maximum number of charac-ters characters
              ters 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  val-ues. values.
              ues.   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
              did not 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 for-mat format
              mat is STRING, the selection is transmitted as 8-bit ASCII characters (i.e.  just in the  form
              returned  by  command, in the system encoding; the UTF8_STRING format always uses UTF-8 as its
              encoding).  If format is ATOM, then the return value from command is divided into fields sepa-rated separated
              rated 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 do not 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  dis-play, display,
       play,  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.

EXAMPLES
       On  X11  platforms,  one of the standard selections available is the SECONDARY selection. Hardly any-thing anything
       thing 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 selection; 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 {} {
                 puts "Lost selection"
              }

SEE ALSO
       clipboard(n)

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



Tk                                                   8.1                                        selection(n)