12.2 Selecting Events

A client selects which types of events it receives from a specific window. The window event-mask attribute, set by the client, determines which event types are selected (see window-event-mask in paragrpah 4.3, Window Attributes). Most types of events are received by a client only if they are selected for some window.

In the X protocol, an event-mask is represented as a bit string. CLX also allows an event mask to be defined by a list of event-mask-class keywords. The functions make-event-keys and make-event-mask can be used to convert between these two forms of an event-mask. In general, including an event-mask-class keyword in an event-mask causes one or more related event types to be selected. The following table describes the event types selected by each event-mask-class keyword.

Event Mask Keyword Event Types Selected
:button-1-motion :motion-notify when :button-1 is down
:button-2-motion :motion-notify when :button-2 is down
:button-3-motion :motion-notify when :button-3 is down
:button-4-motion :motion-notify when :button-4 is down
:button-5-motion :motion-notify when :button-5 is down
:button-motion :motion-notify when any pointer button is down
:button-press :button-press
:button-release :button-release
:colormap-change :colormap-notify
:enter-window :enter-notify
:exposure :exposure
:focus-change :focus-in, :focus-out
:key-press :key-press
:key-release :key-release
:keymap-state :keymap-notify
:leave-window :leave-notify
:owner-grab-button Pointer events while button is grabbed
:pointer-motion :motion-notify
:pointer-motion-hint Single :motion-notify only
:property-change :property-notify
:resize-redirect :resize-request
:structure-notify :circulate-notify, :configure-notify, :destroy-notify, :gravity-notify, :map-notify, :reparent-notify, :unmap-notify
:substructure-redirect :circulate-request, :configure-request, :map-request
:visibility-change :visibility-notify

Some types of events do not have to be selected to be received and therefore are not represented in an event-mask. For example, the copy-plane and copy-area functions cause :graphics-exposure and :no-exposure events to be reported, unless exposures are turned :off in the graphics context (see copy-area and copy-plane in paragrpah 6.2, Area and Plane Operations, and gcontext-exposures in paragraph 5.4.6, Exposures). Also, :selection-clear, :selection-request, :selection-notify and :client-message events can be received at any time, but they are generally sent only to clients using selections (see paragrpah 12.12.7, Client Communications Events). :mapping-notify is always sent to clients when the keyboard mapping is changed.

Any client can select events for any window. A window maintains a separate event-mask for each interested client. In general, multiple clients can select for the same events on a window. After the X server generates an event, it sends it to all clients which selected it. However, the following restrictions apply to sharing window events among multiple clients. For a given window: