'''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 ''window'', ''type'', and ''selection'' is removed.

When ''selection'' is requested, ''windo'' 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 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 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 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 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. 

----

See also:

   * [selection]

----

[Tk syntax help] -
[Category Command]