0.5. Selections
Events:
Selections are one method used by applications to exchange data. By using the property mechanism, applications can exchange data of arbitrary types and can negotiate the type of the data. A selection can be thought of as an indirect property with a dynamic type. That is, rather than having the property stored in the X server, the property is maintained by some client (the owner). A selection is global in nature (considered to belong to the user but be maintained by clients) rather than being private to a particular window subhierarchy or a particular set of clients.
Xlib provides functions that you can use to set, get, or request conversion of selections. This allows applications to implement the notion of current selection, which requires that notification be sent to applications when they no longer own the selection. Applications that support selection often highlight the current selection and so must be informed when another application has acquired the selection so that they can unhighlight the selection.
When a client asks for the contents of a selection, it specifies a selection target type. This target type can be used to control the transmitted representation of the contents. For example, if the selection is "the last thing the user clicked on" and that is currently an image, then the target type might specify whether the contents of the image should be sent in XY format or Z format.
The target type can also be used to control the class of contents transmitted, for example, asking for the "looks" (fonts, line spacing, indentation, and so forth) of a paragraph selection, not the text of the paragraph. The target type can also be used for other purposes. The protocol does not constrain the semantics.
To set the selection owner, use XSetSelectionOwner.
XSetSelectionOwner(display, selection, owner, time) Display *display; Atom selection; Window owner; Time time; display Specifies the connection to the X server. selection Specifies the selection atom. owner Specifies the owner of the specified selection atom. You can pass a window or None. time Specifies the time. You can pass either a times- tamp or CurrentTime.
The XSetSelectionOwner function changes the owner and lastchange time for the specified selection and has no effect if the specified time is earlier than the current last-change time of the specified selection or is later than the current X server time. Otherwise, the last-change time is set to the specified time, with CurrentTime replaced by the current server time. If the owner window is specified as None, then the owner of the selection becomes None (that is, no owner).
Otherwise, the owner of the selection becomes the client executing the request.
If the new owner (whether a client or None) is not the same as the current owner of the selection and the current owner is not None, the current owner is sent a SelectionClear event. If the client that is the owner of a selection is later terminated (that is, its connection is closed) or if the owner window it has specified in the request is later destroyed, the owner of the selection automatically reverts to None, but the last-change time is not affected. The selection atom is uninterpreted by the X server. XGetSelectionOwner returns the owner window, which is reported in SelectionRequest and SelectionClear events. Selections are global to the X server.
XSetSelectionOwner can generate BadAtom and BadWindow errors.
To return the selection owner, use XGetSelectionOwner.
Window XGetSelectionOwner(display, selection) Display *display; Atom selection; display Specifies the connection to the X server. selection Specifies the selection atom whose owner you want returned.
The XGetSelectionOwner function returns the window ID associated with the window that currently owns the specified selection. If no selection was specified, the function returns the constant None. If None is returned, there is no owner for the selection.
XGetSelectionOwner can generate a BadAtom error.
To request conversion of a selection, use XConvertSelection.
XConvertSelection(display, selection, target, property, requestor, time) Display *display; Atom selection, target; Atom property; Window requestor; Time time; display Specifies the connection to the X server. selection Specifies the selection atom. target Specifies the target atom. property Specifies the property name. You also can pass None. requestor Specifies the requestor. time Specifies the time. You can pass either a times- tamp or CurrentTime.
XConvertSelection requests that the specified selection be converted to the specified target type:
The arguments are passed on unchanged in either of the events. There are two predefined selection atoms: PRIMARY and SECONDARY.
XConvertSelection can generate BadAtom and BadWindow errors.
0.13.3. SelectionClear Events
The X server reports SelectionClear events to the client losing ownership of a selection. The X server generates this event type when another client asserts ownership of the selection by calling XSetSelectionOwner.
The structure for this event type contains:
typedef struct {
int type; /* SelectionClear */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window window;
Atom selection;
Time time;
} XSelectionClearEvent;
The selection member is set to the selection atom. The time member is set to the last change time recorded for the selection. The window member is the window that was specified by the current owner (the owner losing the selection) in its XSetSelectionOwner call.
0.13.4. SelectionRequest Events
The X server reports SelectionRequest events to the owner of a selection. The X server generates this event whenever a client requests a selection conversion by calling XConvertSelection for the owned selection.
The structure for this event type contains:
typedef struct {
int type; /* SelectionRequest */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window owner;
Window requestor;
Atom selection;
Atom target;
Atom property;
Time time;
} XSelectionRequestEvent;
The owner member is set to the window that was specified by the current owner in its XSetSelectionOwner call. The requestor member is set to the window requesting the selection. The selection member is set to the atom that names the selection. For example, PRIMARY is used to indicate the primary selection. The target member is set to the atom that indicates the type the selection is desired in. The property member can be a property name or None. The time member is set to the timestamp or CurrentTime value from the ConvertSelection request.
The owner should convert the selection based on the specified target type and send a SelectionNotify event back to the requestor. A complete specification for using selections is given in the X Consortium standard Inter-Client Communication Conventions Manual.
0.13.5. SelectionNotify Events
This event is generated by the X server in response to a ConvertSelection protocol request when there is no owner for the selection. When there is an owner, it should be generated by the owner of the selection by using XSendEvent. The owner of a selection should send this event to a requestor when a selection has been converted and stored as a property or when a selection conversion could not be performed (which is indicated by setting the property member to None).
If None is specified as the property in the ConvertSelection protocol request, the owner should choose a property name, store the result as that property on the requestor window, and then send a SelectionNotify giving that actual property name.
The structure for this event type contains:
typedef struct {
int type; /* SelectionNotify */
unsigned long serial; /* # of last request processed by server */
Bool send_event; /* true if this came from a SendEvent request */
Display *display; /* Display the event was read from */
Window requestor;
Atom selection;
Atom target;
Atom property; /* atom or None */
Time time;
} XSelectionEvent;
The requestor member is set to the window associated with the requestor of the selection. The selection member is set to the atom that indicates the selection. For example, PRIMARY is used for the primary selection. The target member is set to the atom that indicates the converted type. For example, PIXMAP is used for a pixmap. The property member is set to the atom that indicates which property the result was stored on. If the conversion failed, the property member is set to None. The time member is set to the time the conversion took place and can be a timestamp or CurrentTime.