Selecting Input from Extension Input Devices

Selecting Extension Events

To select input from an extended input device, use XSelectExtensionEvent

int XSelectExtensionEvent(display, w, event_list, event_count)
      Display     *display;
      Window       w;
      XEventClass *event_list;
      int          event_count;

Title not available (Selecting Extension Events )

display: Specifies the connection to the X server.
w: Specifies the window whose events you are interested in.
event_list: Specifies the list of event classes that describe the events you are interested in.
event_count: Specifies the count of event classes in the event list.

The XSelectExtensionEvent function requests that the X server report the events associated with the specified list of event classes. Initially, X will not report any of these events. Events are reported relative to a window. If a window is not interested in a device event, it usually propagates to the closest ancestor that is interested, unless the do_not_propagate mask prohibits it.

Multiple clients can select for the same events on the same window with the following restrictions:

Multiple clients can select events on the same window because their event masks are disjoint. When the X server generates an event, it reports it to all interested clients.
Only one client at a time can select a DeviceButtonPress event with automatic passive grabbing enabled, which is associated with the event class DeviceButtonPressGrab. To receive DeviceButtonPress events without automatic passive grabbing, use event class DeviceButtonPress, but do not specify event class DeviceButtonPressGrab. To receive these events with automatic passive grabbing, specify both DeviceButtonPress and DeviceButtonPressGrab.

The server reports the event to all interested clients.

Information contained in the XDevice structure returned by XOpenDevice is used by macros to obtain the event classes that clients use in making XSelectExtensionEvent requests. Currently defined macros include DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelese, DeviceMotionNotify, DeviceFocusIn, DeviceFocusOut, ProximityIn, ProximityOut, DeviceStateNotify, DeviceMappingNotify, ChangeDeviceNotify, DevicePointerMotionHint, DeviceButton1Motion, DeviceButton2Motion, DeviceButton3Motion, DeviceButton4Motion, DeviceButton5Motion, DeviceButtonMotion, DeviceOwnerGrabButton, DeviceButtonPressGrab, and NoExtensionEvent.

To obtain the proper event class for a particular device, one of the above macros is invoked using the XDevice structure for that device. For example,

DeviceKeyPress (*device, type, eventclass);

returns the DeviceKeyPress event type and the eventclass for DeviceKeyPress events from the specified device. DeviceKeyPress from other devices will have a different event class since the event class identifies both the event and the device.

XSelectExtensionEvent can generate a BadWindow or BadClass error.

Getting the List of Currently Selected Extension Events

To get the list of currently selected extension events, use XGetSelectedExtensionEvents.

int XGetSelectedExtensionEvents(display, w,
this_client_event_count_return, this_client_event_list_return,
all_clients_event_count_return, all_clients_event_list_return)
      Display     *display;
      Window       w;
      int         *this_client_event_count_return;
      XEventClass **this_client_event_list_return;
      int         *all_clients_event_count_return;
      XEventClass **all_clients_event_list_return;

Title not available (Getting the List of Currently Selected Extension Events)

display: Specifies the connection to the X server.
w: Specifies the window whose events you are interested in.
this_client_event_count_return: Returns the count of event classes selected by this client.
this_client_event_list_return: Returns a pointer to the list of event classes selected by this client.
all_clients_event_count_return: Returns the count of event classes selected by all clients.
all_clients_event_list_return: Returns a pointer to the list of event classes selected by all clients.

The XGetSelectedExtensionEvents function reports the extension events selected by this client and all clients for the specified window.

This function returns pointers to two event class arrays. One lists the input extension events selected by this client from the specified window. The other lists the event classes selected by all clients from the specified window. You should use XFree to free these two arrays.

XGetSelectedExtensionEvents can generate a BadWindow error.

Sending Extension Events

To send input extension events to a client, use XSendExtensionEvent.

Status XSendExtensionEvent(display, device, destination,
propagate, event_count, event_list, event_send)
      Display     *display;
      XDevice     *device;
      Window       destination;
      Bool         propagate;
      int          event_count;
      XEventClass *event_list;
      XEvent      *event_send;

Title not available (Sending Extension Events )

display: Specifies the connection to the X server.
device: Specifies the device from which the events are to be sent.
destination: Specifies the window the event is to be sent to. You can pass a window id, PointerWindow, or InputFocus.
propagate: Specifies a Boolean value that is either True or False.
event_count: Specifies the count of XEventClasses in event_list.
event_list: Specifies the list of event selections to be used.
event_send: Specifies a pointer to the event that is to be sent.

The XSendExtensionEvent function identifies the destination window, determines which clients should receive the specified events, and ignores any active grabs. This function requires you to pass an event class list. For a discussion of the valid event class names, see XOpenDevice(3X11). This function uses the destination argument to identify the destination window as follows:

If destination is PointerWindow, the destination window is the window that contains the pointer.
If destination is InputFocus and if the focus window contains the pointer, the destination window is the window that contains the pointer; otherwise, the destination window is the focus window.

To determine which clients should receive the specified events, XSendExtensionEvent uses the propagate argument as follows:

If event_count is zero, the event is sent to the client that created the destination window. If that client no longer exists, no event is sent.
If propagate is False, the event is sent to every client selecting on destination any of the event types in the event_list array.
If propagate is True and no clients have selected from the destination window any of the events in the event_list array, the destination is replaced with the closest ancestor of destination for which some client has selected one of the specified events, and for which no intervening window has that type in its do-not-propagate-mask. If no such window exists or if the window is an ancestor of the focus window and InputFocus was originally specified as the destination, the event is not sent to any clients. Otherwise, the event is reported to every client selecting on the final destination any of the events specified in event_list.

The event in the XEvent structure must be one of the events defined by the input extension (or a BadValue error results) so that the X server can correctly byte-swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the X server except to force send_event to True in the forwarded event and to set the serial number in the event correctly.

XSendExtensionEvent returns zero if the conversion to wire protocol format failed and returns nonzero otherwise. XSendExtensionEvent can generate BadDevice, BadValue, BadClass, and BadWindow errors.

Getting the dont-propagate-list

Input extension events are propagated to ancestor windows unless some client specifies otherwise.

Grabs of extension input devices may alter the set of windows that receive a particular input extension event.

To determine which events will not be propagated from a given window, use XGetDeviceDontPropagateList.

XEventClass *XGetDeviceDontPropagateList(display, window,
count_return)
      Display *display;
      Window   window;
      int     *count_return;

Title not available (Getting the dont-propagate-list )

display: Specifies the connection to the X server.
window: Specifies the window whose dont-propagate-list is to be queried.
count_return: Returns the number of event classes in the list returned by this request.

The XGetDeviceDontPropagateList function returns a list of input extension events that will not be propagated to ancestors of the event window. An array of event classes is returned that identifies which events will not be propagated.

XGetDeviceDontPropagateList can generate a BadClass or BadWindow error.

You should use XFree to free the data returned by this function.

Changing the dont-propagate-list

Suppression of event propagation is not allowed for all input extension events. If a specified event class is one that cannot be suppressed, a BadClass error will result. Events whose propagation can be suppressed include: DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify, ProximityIn, and ProximityOut.

To change which events will not be propagated from a given window, use XChangeDeviceDontPropagateList.

int XChangeDeviceDontPropagateList(display, window,
count, event_list, mode)
      Display     *display;
      Window       window;
      int          count;
      XEventClass *event_list;
      int          mode;

Title not available (Changing the dont-propagate-list )

display: Specifies the connection to the X server.
window: Specifies the window whose dont-propagate-list is to be modified.
count: Specifies the number of event classes in the list.
event_list: Specifies a pointer to a list of event classes.
mode: Specifies the mode. You can pass AddToList, or DeleteFromList.

The XChangeDeviceDontPropagateList function modifies the list of input extension events that should not be propagated to ancestors of the event window. This function allows extension events to be added to or deleted from that list. By default, all events are propagated to ancestor windows. Once modified, the list remains modified for the life of the window. Events are not removed from the list because the client that added them has terminated.

XChangeDeviceDontPropagateList can generate a BadDevice, BadClass, or BadValue error.

Getting Extended Device Motion History

To get the device motion history, use XGetDeviceMotionEvents.

XDeviceTimeCoord *XGetDeviceMotionEvents(display, device,
start, stop, nevents_return, mode_return, axis_count_return)
      Display *display;
      XDevice *device;
      Time     start, stop;
      int     *nevents_return;
      int     *mode_return;
      int     *axis_count_return;

Title not available (Getting Extended Device Motion History )

display: Specifies the connection to the X server.
device: Specifies the device whose motion history is to be queried.
start stop: Specify the time interval in which the events are returned from the motion history buffer. You can pass a timestamp or CurrentTime.
nevents_return: Returns the number of events from the motion history buffer.
mode_return: Returns the mode of the device ( Absolute or Relative).
axis_count_return: Returns the count of axes being reported.

The server may retain the recent history of the device motion and do so to a finer granularity than is reported by DeviceMotionNotify events. The XGetDeviceMotionEvents function makes this history available.

The XGetDeviceMotionEvents function returns all events in the motion history buffer that fall between the specified start and stop times, inclusive. If the start time is later than the stop time or if the start time is in the future, no events are returned. If the stop time is in the future, it is equivalent to specifying CurrentTime.

The mode indicates whether the device is reporting absolute positional data (mode=Absolute) or relative motion data (mode=Relative). These constants are defined in the file XI.h. The axis_count returns the number of axes or valuators being reported by the device.

XGetDeviceMotionEvents can generate a BadDevice, BadMatch or BadWindow error.

The XDeviceTimeCoord structure contains:

typedef struct {
        Time time;
        int *data;
} XDeviceTimeCoord

The time member is set to the time, in milliseconds. The data member is a pointer to an array of integers. These integers are set to the values of each valuator or axis reported by the device.

There is one element in the array per axis of motion reported by the device. The value of the array elements depends on the mode of the device. If the mode is Absolute, the values are the raw values generated by the device. These may be scaled by client programs using the maximum values that the device can generate. The maximum value for each axis of the device is reported in the max_val field of the XAxisInfo structure returned by the XListInputDevices function. If the mode is Relative, the data values are the relative values generated by the device.

You should use XFreeDeviceMotionEvents to free the data returned by this function.

XGetDeviceMotionEvents can generate a BadDevice or BadMatch error.

Freeing the Device Motion Array

To free the device motion array, use XFreeDeviceMotionEvents.

XFreeDeviceMotionEvents(events)
     XDeviceTimeCoord *events;

Title not available (Freeing the Device Motion Array )

events: Specifies the pointer to the XDeviceTimeCoord array returned by a previous call to XGetDeviceMotionEvents.

This function frees the array of motion information.