13.11.7 Client Communications Events

The client communications events discussed in the following paragraphs are: :client-message, :property-notify, :selection-clear, :selection-request, and :selection-notify.

Event Type: :client-message

The :client-message event is generated exclusively by client calls to send-event. The X server places no interpretation on the type or content of data sent in a :client-message. A client can neither select :client-message events nor avoid receiving them.

window

event-window

Type window.

The window receiving the event.

type

Type keyword.

An xatom keyword that specifies the type of client message. Interpretation of the type is determined solely by agreement between the sending and receiving clients.

format

Type (member 8 16 32).

An integer that specifies whether data should be viewed as a sequence of 8-bit, 16-bit, or 32-bit quantities.

data

Type (sequence integer).

The data content of the client message. data always consists of 160 bytes – depending on format, either 20 8-bit values, 10 16-bit values or 5 32-bit values. The amount of this data actually used by a particular client message depends on the type.

Event Type: :property-notify

Selected by: :property-change.

The :property-notify event is generated when a window property is changed or deleted.

window

event-window

Type window.

The window receiving the event.

atom

Type keyword.

The property that was changed or deleted.

state

Type (member :new-value :deleted).

state is :new-value if the property was changed using change-property or rotate-properties, even if zero-length data was added or if all or part of the property was replaced with identical data. state is :deleted if the property was deleted using delete-property or get-property.

time

Type timestamp.

The server time when the property was changed or deleted.

Event Type: :selection-clear

The :selection-clear event is reported to the previous owner of a selection when the owner of the selection is changed. The selection owner is changed by a client using setf. A client can neither select :selection-clear events nor avoid receiving them.

window

event-window

Type window.

The window losing ownership of the selection.

selection

Type keyword.

The name of the selection.

time

Type timestamp.

The last-change time recorded for the selection.

Event Type: :selection-notify

The :selection-notify event is sent to a client calling convert-selection. :selection-notify reports the result of the client request to return the current value of a selection into a particular form. :selection-notify is sent using send-event by the owner of the selection or (if no owner exists) by the X server. A client can neither select :selection-notify events nor avoid receiving them.

NOTE: Standard conventions for inter-client communication require the following additional steps in processing a :selection-notify event:

1. The client receiving this event should call get-property to return the converted selection value.
2. After receiving the selection value, the property should then be deleted (either by using the :delete-p argument to get-property or by calling delete-property).

window

event-window

Type window.

The requestor window given in the call to convert-selection.

selection

Type keyword.

The selection to be converted.

target

Type keyword.

An xatom specifying the type of the converted selection value. This is the same target type given in the call to convert-selection.

property

Type (or null keyword).

The window property containing the converted selection. If the property is nil, then either the selection has no owner or the owner could not perform the conversion to the target type.

time

Type timestamp.

The timestamp from the client call to convert-selection.

Event Type: :selection-request

The :selection-request event is reported to the owner of a selection when a client calls convert-selection. This event requests the selection owner to convert the current value of a selection into a specified form and to return it to the requestor. A client can neither select :selection-request events nor avoid receiving them.

The selection owner should respond to a :selection-request event by performing the following steps:

1. Convert the current selection value to the target type.
2. Store the converted selection value in the property. If property is nil, then the owner should choose the property.
3. Call send-event to send a :selection-notify event to the requestor containing the property with the converted value. If the selection could not be converted to the target type, then a nil property should be sent. The :selection, :target, and :time arguments to send-event should be the same as those received in the :selection-request event. The event-mask argument to send-event should be nil; that is, the :selection-notify event should be sent to client that created the requestor.

NOTE: Standard conventions for inter-client communication require the following additional steps in processing a :selection-request event:

1. The property used to store the selection value must belong to the requestor.
2. If the property is nil, the target type atom should be used as the property name.
3. If the window did not actually own the selection at the given time, the request should be refused, just as if it could not be converted to the target type.

window

event-window

Type window.

The selection owner receiving the event.

requestor

Type window.

The window requesting the converted selection.

selection

Type keyword.

The selection to be converted.

target

Type keyword.

An xatom specifying the type of the converted selection value.

property

Type (or null keyword).

A requestor window property.

time

Type timestamp.

The timestamp sent in the client convert-selection request.