--- name: "selection" section: "n" platform: "macos" package: "tcl" version: "152" release: "macOS 26.5" platforms: ["linux", "macos"] url: "https://new.carta.tech/selection/n" --- # selection(n) Manipulate the X 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). 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 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 selection is to be returned (the desired 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 selection *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 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 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 *format* 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 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 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 display, 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 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 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)](/clipboard/n.md) ## KEYWORDS clear, format, handler, ICCCM, own, selection, target, type