Manual Pages for UNIX Darwin command on man selection

selection(n) Tk Built-In Commands selection(n)

NAME

selection - Manipulate the X selection

SYNOPSIS

sseelleeccttiioonn 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

cclliippbbooaarrdd command may also be used. The first argument to sseelleeccttiioonn determines the format of the rest of the arguments and the behavior of the command. The following forms are currently supported:

sseelleeccttiioonn cclleeaarr ?-ddiissppllaayyooff window? ?-sseelleeccttiioonn 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 Communi-

cation Conventions Manual for complete details. Selection defaults to PRIMARY and window defaults to ``.''. Returns an empty string.

sseelleeccttiioonn ggeett ?-ddiissppllaayyooff window? ?-sseelleeccttiioonn selection? ?-ttyyppee type?

Retrieves the value of selection from window's display and

returns it as a result. Selection defaults to PRIMARY and win-

dow defaults to ``.''. Type specifies the form in which the

selection is to be returned (the desired ``target'' for conver-

sion, in ICCCM terminology), and should be an atom name such as

STRING or FILENAME; 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 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

sseelleeccttiioonn command converts it to string format as a collection

of fields separated by spaces: atoms are converted to their tex-

tual names, and anything else is converted to hexadecimal inte-

gers.

sseelleeccttiioonn hhaannddllee ?-sseelleeccttiioonn selection? ?-ttyyppee type? ?-ffoorrmmaatt 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 sseelleeccttiioonn ggeett 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 win-

dow, 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 additional numbers are offset and max- |

Chars: 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 col-

umn of Table 2 of the ICCCM), and defaults to STRING. If format

is STRING, the selection is transmitted as 8-bit ASCII charac-

ters (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 selec-

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

sseelleeccttiioonn oowwnn ?-ddiissppllaayyooff window? ?-sseelleeccttiioonn selection?

sseelleeccttiioonn oowwnn ?-ccoommmmaanndd command? ?-sseelleeccttiioonn selection? window

The first form of sseelleeccttiioonn oowwnn 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 sseelleeccttiioonn oowwnn causes window to become the new owner