diff options
Diffstat (limited to 'specs')
| -rw-r--r-- | specs/Makefile.am | 6 | ||||
| -rw-r--r-- | specs/XIproto.txt | 3724 |
2 files changed, 1884 insertions, 1846 deletions
diff --git a/specs/Makefile.am b/specs/Makefile.am index ad51453..a83cf40 100644 --- a/specs/Makefile.am +++ b/specs/Makefile.am @@ -2,15 +2,13 @@ if ENABLE_SPECS if HAVE_ASCIIDOC -doc_DATA = XI2proto.html -dist_doc_DATA = XI2proto.txt +doc_DATA = XI2proto.html XIproto.html +dist_doc_DATA = XI2proto.txt XIproto.txt %.html: %.txt $(AM_V_GEN)$(ASCIIDOC) -o $@ $< CLEANFILES = $(doc_DATA) -EXTRA_DIST = XIproto.txt - endif endif diff --git a/specs/XIproto.txt b/specs/XIproto.txt index 35ab1c9..1095a26 100644 --- a/specs/XIproto.txt +++ b/specs/XIproto.txt @@ -1,4 +1,6 @@ - X11 Input Extension Protocol Specification +X11 Input Extension Protocol Specification +========================================== + Version 1.0 X Consortium Standard X Version 11, Release 6.8 @@ -72,154 +74,160 @@ OTHER DEALINGS IN THE SOFTWARE. 1. Input Extension Overview - - This document defines an extension to the X11 protocol to - support input devices other than the core X keyboard and - pointer. An accompanying document defines a corresponding - extension to Xlib (similar extensions for languages other than - C are anticipated). This first section gives an overview of the - input extension. The next section defines the new protocol - requests defined by the extension. We conclude with a - description of the new input events generated by the additional - input devices. - - This document only describes the behaviour of servers supporting - up to the X Input Extension 1.5. For servers supporting the X - Input Extensions 2.0, see XI2proto.txt. New clients are discouraged - from using this protocol specification. Instead, the use of XI 2.x - is recommended. +--------------------------- + +This document defines an extension to the X11 protocol to +support input devices other than the core X keyboard and +pointer. An accompanying document defines a corresponding +extension to Xlib (similar extensions for languages other than +C are anticipated). This first section gives an overview of the +input extension. The next section defines the new protocol +requests defined by the extension. We conclude with a +description of the new input events generated by the additional +input devices. + +This document only describes the behaviour of servers supporting +up to the X Input Extension 1.5. For servers supporting the X +Input Extensions 2.0, see XI2proto.txt. New clients are discouraged +from using this protocol specification. Instead, the use of XI 2.x +is recommended. 1.1 Design Approach +~~~~~~~~~~~~~~~~~~~ - The design approach of the extension is to define requests and - events analogous to the core requests and events. This allows - extension input devices to be individually distinguishable from - each other and from the core input devices. These requests and - events make use of a device identifier and support the - reporting of n-dimensional motion data as well as other data - that is not reportable via the core input events. +The design approach of the extension is to define requests and +events analogous to the core requests and events. This allows +extension input devices to be individually distinguishable from +each other and from the core input devices. These requests and +events make use of a device identifier and support the +reporting of n-dimensional motion data as well as other data +that is not reportable via the core input events. 1.2 Core Input Devices - - The X server core protocol supports two input devices: a - pointer and a keyboard. The pointer device has two major - functions. First, it may be used to generate motion information - that client programs can detect. Second, it may also be used to - indicate the current location and focus of the X keyboard. To - accomplish this, the server echoes a cursor at the current - position of the X pointer. Unless the X keyboard has been - explicitly focused, this cursor also shows the current location - and focus of the X keyboard. The X keyboard is used to generate - input that client programs can detect. - - In servers supporting XI 1.4 and above, the core pointer and - the core keyboard are virtual devices that do not represent a - physical device connected to the host computer. - In servers supporting XI 2.0 and above, there may be multiple - core pointers and keyboards. Refer to XI2proto.txt for more - information. - - The X keyboard and X pointer are referred to in this document - as the core devices, and the input events they generate - (KeyPress, KeyRelease, ButtonPress, ButtonRelease, and - MotionNotify) are known as the core input events. All other - input devices are referred to as extension input devices and - the input events they generate are referred to as extension - input events. - - In servers supporting only XI 1.x, this input extension does - not change the behavior or functionality of the core input - devices, core events, or core protocol requests, with the - exception of the core grab requests. These requests may affect - the synchronization of events from extension devices. See the - explanation in the section titled "Event Synchronization and - Core Grabs". - - Selection of the physical devices to be initially used by the - server as the core devices is left implementation-dependent. - Requests are defined that allow client programs to change which - physical devices are used as the core devices. +~~~~~~~~~~~~~~~~~~~~~~ + +The X server core protocol supports two input devices: a +pointer and a keyboard. The pointer device has two major +functions. First, it may be used to generate motion information +that client programs can detect. Second, it may also be used to +indicate the current location and focus of the X keyboard. To +accomplish this, the server echoes a cursor at the current +position of the X pointer. Unless the X keyboard has been +explicitly focused, this cursor also shows the current location +and focus of the X keyboard. The X keyboard is used to generate +input that client programs can detect. + +In servers supporting XI 1.4 and above, the core pointer and +the core keyboard are virtual devices that do not represent a +physical device connected to the host computer. +In servers supporting XI 2.0 and above, there may be multiple +core pointers and keyboards. Refer to XI2proto.txt for more +information. + +The X keyboard and X pointer are referred to in this document +as the core devices, and the input events they generate +(KeyPress, KeyRelease, ButtonPress, ButtonRelease, and +MotionNotify) are known as the core input events. All other +input devices are referred to as extension input devices and +the input events they generate are referred to as extension +input events. + +In servers supporting only XI 1.x, this input extension does +not change the behavior or functionality of the core input +devices, core events, or core protocol requests, with the +exception of the core grab requests. These requests may affect +the synchronization of events from extension devices. See the +explanation in the section titled "Event Synchronization and +Core Grabs". + +Selection of the physical devices to be initially used by the +server as the core devices is left implementation-dependent. +Requests are defined that allow client programs to change which +physical devices are used as the core devices. 1.3 Extension Input Devices - - The input extension v1.x controls access to input devices other - than the X keyboard and X pointer. It allows client programs to - select input from these devices independently from each other - and independently from the core devices. - - A client that wishes to access a specific device must first - determine whether that device is connected to the X server. - This is done through the ListInputDevices request, which will - return a list of all devices that can be opened by the X - server. A client can then open one or more of these devices - using the OpenDevice request, specify what events they are - interested in receiving, and receive and process input events - from extension devices in the same way as events from the X - keyboard and X pointer. Input events from these devices are of - extension types ( DeviceKeyPress, DeviceKeyRelease, - DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify, - etc.) and contain a device identifier so that events of the - same type coming from different input devices can be - distinguished. - - Any kind of input device may be used as an extension input - device. Extension input devices may have 0 or more keys, 0 or - more buttons, and may report 0 or more axes of motion. Motion - may be reported as relative movements from a previous position - or as an absolute position. All valuators reporting motion - information for a given extension input device must report the - same kind of motion information (absolute or relative). - - This extension is designed to accommodate new types of input - devices that may be added in the future. The protocol requests - that refer to specific characteristics of input devices - organize that information by input classes. Server implementors - may add new classes of input devices without changing the - protocol requests. Input classes are unique numbers registered - with the X Consortium. Each extension input device may support - multiple input classes. - - In XI 1.x, all extension input devices are treated like the - core X keyboard in determining their location and focus. The - server does not track the location of these devices on an - individual basis, and therefore does not echo a cursor to - indicate their current location. Instead, their location is - determined by the location of the core X pointer. Like the core - X keyboard, some may be explicitly focused. If they are not - explicitly focused, their focus is determined by the location - of the core X pointer. - - Most input events reported by the server to a client are of - fixed size (32 bytes). In order to represent the change in - state of an input device the extension may need to generate a - sequence of input events. A client side library (such as Xlib) - will typically take these raw input events and format them into - a form more convenient to the client. +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The input extension v1.x controls access to input devices other +than the X keyboard and X pointer. It allows client programs to +select input from these devices independently from each other +and independently from the core devices. + +A client that wishes to access a specific device must first +determine whether that device is connected to the X server. +This is done through the ListInputDevices request, which will +return a list of all devices that can be opened by the X +server. A client can then open one or more of these devices +using the OpenDevice request, specify what events they are +interested in receiving, and receive and process input events +from extension devices in the same way as events from the X +keyboard and X pointer. Input events from these devices are of +extension types ( DeviceKeyPress, DeviceKeyRelease, +DeviceButtonPress, DeviceButtonRelease, DeviceMotionNotify, +etc.) and contain a device identifier so that events of the +same type coming from different input devices can be +distinguished. + +Any kind of input device may be used as an extension input +device. Extension input devices may have 0 or more keys, 0 or +more buttons, and may report 0 or more axes of motion. Motion +may be reported as relative movements from a previous position +or as an absolute position. All valuators reporting motion +information for a given extension input device must report the +same kind of motion information (absolute or relative). + +This extension is designed to accommodate new types of input +devices that may be added in the future. The protocol requests +that refer to specific characteristics of input devices +organize that information by input classes. Server implementors +may add new classes of input devices without changing the +protocol requests. Input classes are unique numbers registered +with the X Consortium. Each extension input device may support +multiple input classes. + +In XI 1.x, all extension input devices are treated like the +core X keyboard in determining their location and focus. The +server does not track the location of these devices on an +individual basis, and therefore does not echo a cursor to +indicate their current location. Instead, their location is +determined by the location of the core X pointer. Like the core +X keyboard, some may be explicitly focused. If they are not +explicitly focused, their focus is determined by the location +of the core X pointer. + +Most input events reported by the server to a client are of +fixed size (32 bytes). In order to represent the change in +state of an input device the extension may need to generate a +sequence of input events. A client side library (such as Xlib) +will typically take these raw input events and format them into +a form more convenient to the client. 1.4 Event Classes - - In the core protocol a client registers interest in receiving - certain input events directed to a window by modifying that - window's event-mask. Most of the bits in the event mask are - already used to specify interest in core X events. The input - extension specifies a different mechanism by which a client can - express interest in events generated by this extension. - - When a client opens a extension input device via the OpenDevice - request, an XDevice structure is returned. Macros are provided - that extract 32-bit numbers called event classes from that - structure, that a client can use to register interest in - extension events via the SelectExtensionEvent request. The - event class combines the desired event type and device id, and - may be thought of as the equivalent of core event masks. +----------------- + +In the core protocol a client registers interest in receiving +certain input events directed to a window by modifying that +window's event-mask. Most of the bits in the event mask are +already used to specify interest in core X events. The input +extension specifies a different mechanism by which a client can +express interest in events generated by this extension. + +When a client opens a extension input device via the OpenDevice +request, an XDevice structure is returned. Macros are provided +that extract 32-bit numbers called event classes from that +structure, that a client can use to register interest in +extension events via the SelectExtensionEvent request. The +event class combines the desired event type and device id, and +may be thought of as the equivalent of core event masks. 1.5 Input Classes +~~~~~~~~~~~~~~~~~ - Some of the input extension requests divide input devices into - classes based on their functionality. This is intended to allow - new classes of input devices to be defined at a later time - without changing the semantics of these requests. The following - input device classes are currently defined: +Some of the input extension requests divide input devices into +classes based on their functionality. This is intended to allow +new classes of input devices to be defined at a later time +without changing the semantics of these requests. The following +input device classes are currently defined: KEY The device reports key events. @@ -244,102 +252,105 @@ DeviceStateNotify macros may be invoked passing the XDevice structure returned for this device. - Each extension input device may support multiple input classes. - Additional classes may be added in the future. Requests that - support multiple input classes, such as the ListInputDevices - function that lists all available input devices, organize the - data they return by input class. Client programs that use these - requests should not access data unless it matches a class - defined at the time those clients were compiled. In this way, - new classes can be added without forcing existing clients that - use these requests to be recompiled. +Each extension input device may support multiple input classes. +Additional classes may be added in the future. Requests that +support multiple input classes, such as the ListInputDevices +function that lists all available input devices, organize the +data they return by input class. Client programs that use these +requests should not access data unless it matches a class +defined at the time those clients were compiled. In this way, +new classes can be added without forcing existing clients that +use these requests to be recompiled. 2. Requests +----------- - Extension input devices are accessed by client programs through - the use of new protocol requests. This section summarizes the - new requests defined by this extension. The syntax and type - definitions used below follow the notation used for the X11 - core protocol. +Extension input devices are accessed by client programs through +the use of new protocol requests. This section summarizes the +new requests defined by this extension. The syntax and type +definitions used below follow the notation used for the X11 +core protocol. 2.1 Getting the Extension Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The GetExtensionVersion request returns version information - about the input extension. +The GetExtensionVersion request returns version information +about the input extension. - GetExtensionVersion - name: STRING - => - present: BOOL - protocol-major-version: CARD16 - protocol-minor-version: CARD16 + GetExtensionVersion + name: STRING + => + present: BOOL + protocol-major-version: CARD16 + protocol-minor-version: CARD16 - The protocol version numbers returned indicate the version of - the input extension supported by the target X server. The - version numbers can be compared to constants defined in the - header file XI.h. Each version is a superset of the previous - versions. +The protocol version numbers returned indicate the version of +the input extension supported by the target X server. The +version numbers can be compared to constants defined in the +header file XI.h. Each version is a superset of the previous +versions. - The name must be the name of the Input Extension as defined - in the header file XI.h. +The name must be the name of the Input Extension as defined +in the header file XI.h. 2.2 Listing Available Devices - - A client that wishes to access a specific device must first - determine whether that device is connected to the X server. - This is done through the ListInputDevices request, which will - return a list of all devices that can be opened by the X - server. - - ListInputDevices - => - input-devices: ListOfDeviceInfo - - where - - DEVICEINFO: - [type: ATOM - id: CARD8 - num_classes: CARD8 - use: {IsXKeyboard, IsXPointer, IsXExtensionPointer, - IsXExtensionKeyboard, IsExtensionDevice} - info: LISTofINPUTINFO - name: STRING8] - - INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO} - KEYINFO: - [class: CARD8 - length: CARD8 - min-keycode: KEYCODE - max-keycode: KEYCODE - num-keys: CARD16] - BUTTONINFO: - [class: CARD8 - length: CARD8 - num-buttons: CARD16] - VALUATORINFO: - [class: CARD8 - length: CARD8 - num_axes: CARD8 - mode: SETofDEVICEMODE - motion_buffer_size: CARD32 - axes: LISTofAXISINFO] - - AXISINFO: - [resolution: CARD32 - min-val: CARD32 - max-val: CARD32] - DEVICEMODE: {Absolute, Relative} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +A client that wishes to access a specific device must first +determine whether that device is connected to the X server. +This is done through the ListInputDevices request, which will +return a list of all devices that can be opened by the X +server. + + ListInputDevices + => + input-devices: ListOfDeviceInfo + +where + + DEVICEINFO: + [type: ATOM + id: CARD8 + num_classes: CARD8 + use: {IsXKeyboard, IsXPointer, IsXExtensionPointer, + IsXExtensionKeyboard, IsExtensionDevice} + info: LISTofINPUTINFO + name: STRING8] + + INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO} + KEYINFO: + [class: CARD8 + length: CARD8 + min-keycode: KEYCODE + max-keycode: KEYCODE + num-keys: CARD16] + BUTTONINFO: + [class: CARD8 + length: CARD8 + num-buttons: CARD16] + VALUATORINFO: + [class: CARD8 + length: CARD8 + num_axes: CARD8 + mode: SETofDEVICEMODE + motion_buffer_size: CARD32 + axes: LISTofAXISINFO] + + AXISINFO: + [resolution: CARD32 + min-val: CARD32 + max-val: CARD32] + DEVICEMODE: {Absolute, Relative} Errors: None - This request returns a list of all devices that can be opened - by the X server, including the core X keyboard and X pointer. - Some implementations may open all input devices as part of X - initialization, while others may not open an input device until - requested to do so by a client program. +This request returns a list of all devices that can be opened +by the X server, including the core X keyboard and X pointer. +Some implementations may open all input devices as part of X +initialization, while others may not open an input device until +requested to do so by a client program. - The information returned for each device is as follows: +The information returned for each device is as follows: type The type field is of type Atom and indicates the nature @@ -422,8 +433,8 @@ that are contained in this input class. The length includes the class and length fields. - The remaining information returned for input class - KEYCLASS is as follows: +The remaining information returned for input class +KEYCLASS is as follows: min_keycode min_keycode is of type KEYCODE. It specifies the @@ -439,15 +450,15 @@ num_keys is a cardinal value that specifies the number of keys that the device has. - The remaining information returned for input class - BUTTONCLASS is as follows: +The remaining information returned for input class +BUTTONCLASS is as follows: num_buttons num_buttons is a cardinal value that specifies the number of buttons that the device has. - The remaining information returned for input class - VALUATORCLASS is as follows: +The remaining information returned for input class +VALUATORCLASS is as follows: mode mode is a constant that has one of the following @@ -465,8 +476,8 @@ The axes field contains a pointer to an AXISINFO struture. - The information returned for each axis reported by the - device is: +The information returned for each axis reported by the +device is: resolution The resolution is a cardinal value in @@ -485,34 +496,35 @@ max_val field will contain 0. 2.3 Enabling Devices - - Client programs that wish to access an extension device must - request that the server open that device. This is done via the - OpenDevice request. - - OpenDevice - id: CARD8 - => - DEVICE: - [device_id: XID - num_classes: INT32 - classes: LISTofINPUTCLASSINFO] - INPUTCLASSINFO: - [input_class: CARD8 - event_type_base: CARD8] +~~~~~~~~~~~~~~~~~~~~ + +Client programs that wish to access an extension device must +request that the server open that device. This is done via the +OpenDevice request. + + OpenDevice + id: CARD8 + => + DEVICE: + [device_id: XID + num_classes: INT32 + classes: LISTofINPUTCLASSINFO] + INPUTCLASSINFO: + [input_class: CARD8 + event_type_base: CARD8] Errors: Device - This request returns the event classes to be used by the client - to indicate which events the client program wishes to receive. - Each input class may report several event classes. For example, - input class Keys reports DeviceKeyPress and DeviceKeyRelease - event classes. Input classes are unique numbers registered with - the X Consortium. Input class Other exists to report event - classes that are not specific to any one input class, such as - DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify. +This request returns the event classes to be used by the client +to indicate which events the client program wishes to receive. +Each input class may report several event classes. For example, +input class Keys reports DeviceKeyPress and DeviceKeyRelease +event classes. Input classes are unique numbers registered with +the X Consortium. Input class Other exists to report event +classes that are not specific to any one input class, such as +DeviceMappingNotify, ChangeDeviceNotify, and DeviceStateNotify. - The information returned for each device is as follows: +The information returned for each device is as follows: device_id The device_id is a number that uniquely identifies the @@ -538,594 +550,606 @@ classes. This is described in the section of this document entitled "Selecting Extension Device Events". - The information in the InputClassInfo reflects the state of - this device at the time the request was processed. +The information in the InputClassInfo reflects the state of +this device at the time the request was processed. - Before it exits, the client program should explicitly request - that the server close the device. This is done via the - CloseDevice request. +Before it exits, the client program should explicitly request +that the server close the device. This is done via the +CloseDevice request. - A client may open the same extension device more than once. - Requests after the first successful one return an additional - XDevice structure with the same information as the first, but - otherwise have no effect. A single CloseDevice request will - terminate that client's access to the device. +A client may open the same extension device more than once. +Requests after the first successful one return an additional +XDevice structure with the same information as the first, but +otherwise have no effect. A single CloseDevice request will +terminate that client's access to the device. - Closing a device releases any active or passive grabs the - requesting client has established. If the device is frozen only - by an active grab of the requesting client, the queued events - are released when the client terminates. +Closing a device releases any active or passive grabs the +requesting client has established. If the device is frozen only +by an active grab of the requesting client, the queued events +are released when the client terminates. - If a client program terminates without closing a device, the - server will automatically close that device on behalf of the - client. This does not affect any other clients that may be - accessing that device. +If a client program terminates without closing a device, the +server will automatically close that device on behalf of the +client. This does not affect any other clients that may be +accessing that device. - CloseDevice: - device: DEVICE + CloseDevice: + device: DEVICE Errors: Device 2.4 Changing The Mode Of A Device - - Some devices are capable of reporting either relative or - absolute motion data. To change the mode of a device from - relative to absolute, use the SetDeviceMode request. The valid - values are Absolute or Relative. - - This request will fail and return DeviceBusy if another client - already has the device open with a different mode. It will fail - and return AlreadyGrabbed if another client has the device - grabbed. The request will fail with a BadMatch error if the - device has no valuators and reports no axes of motion. The - request will fail with a BadMode error if the requested mode - is not supported by the device. - - SetDeviceMode - device:DEVICE - mode: {Absolute, Relative} - => - status: {Success, DeviceBusy, AlreadyGrabbed} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some devices are capable of reporting either relative or +absolute motion data. To change the mode of a device from +relative to absolute, use the SetDeviceMode request. The valid +values are Absolute or Relative. + +This request will fail and return DeviceBusy if another client +already has the device open with a different mode. It will fail +and return AlreadyGrabbed if another client has the device +grabbed. The request will fail with a BadMatch error if the +device has no valuators and reports no axes of motion. The +request will fail with a BadMode error if the requested mode +is not supported by the device. + + SetDeviceMode + device:DEVICE + mode: {Absolute, Relative} + => + status: {Success, DeviceBusy, AlreadyGrabbed} Errors: Device, Match, Mode 2.5 Initializing Valuators on an Input Device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Some devices that report absolute positional data can be - initialized to a starting value. Devices that are capable of - reporting relative motion or absolute positional data may - require that their valuators be initialized to a starting value - after the mode of the device is changed to Absolute. To - initialize the valuators on such a device, use the - SetDeviceValuators request. - - SetDeviceValuators - device: DEVICE - first_valuator: CARD8 - num_valuators: CARD8 - valuators: LISTOFINT32 - => - status: {Success, AlreadyGrabbed} +Some devices that report absolute positional data can be +initialized to a starting value. Devices that are capable of +reporting relative motion or absolute positional data may +require that their valuators be initialized to a starting value +after the mode of the device is changed to Absolute. To +initialize the valuators on such a device, use the +SetDeviceValuators request. + + SetDeviceValuators + device: DEVICE + first_valuator: CARD8 + num_valuators: CARD8 + valuators: LISTOFINT32 + => + status: {Success, AlreadyGrabbed} Errors: Length, Device, Match, Value - This request initializes the specified valuators on the - specified extension input device. Valuators are numbered - beginning with zero. Only the valuators in the range specified - by first_valuator and num_valuators are set. If the number of - valuators supported by the device is less than the expression - first_valuator + num_valuators, a Value error will result. +This request initializes the specified valuators on the +specified extension input device. Valuators are numbered +beginning with zero. Only the valuators in the range specified +by first_valuator and num_valuators are set. If the number of +valuators supported by the device is less than the expression +first_valuator + num_valuators, a Value error will result. - If the request succeeds, Success is returned. If the specifed - device is grabbed by some other client, the request will fail - and a status of AlreadyGrabbed will be returned. +If the request succeeds, Success is returned. If the specifed +device is grabbed by some other client, the request will fail +and a status of AlreadyGrabbed will be returned. 2.6 Getting Input Device Controls +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - GetDeviceControl - device: DEVICE - control: XID - => - controlState: {DeviceState} + GetDeviceControl + device: DEVICE + control: XID + => + controlState: {DeviceState} - where +where - DeviceState: DeviceResolutionState + DeviceState: DeviceResolutionState Errors: Length, Device, Match, Value - This request returns the current state of the specified device - control. The device control must be supported by the target - server and device or an error will result. - - If the request is successful, a pointer to a generic - DeviceState structure will be returned. The information - returned varies according to the specified control and is - mapped by a structure appropriate for that control. - - GetDeviceControl will fail with a BadValue error if the server - does not support the specified control. It will fail with a - BadMatch error if the device does not support the specified - control. - - Supported device controls and the information returned for them - include: - - DEVICE_RESOLUTION: - [control: CARD16 - length: CARD16 - num_valuators: CARD8 - resolutions: LISTofCARD32 - min_resolutions: LISTofCARD32 - max_resolutions: LISTofCARD32] - - This device control returns a list of valuators and the range - of valid resolutions allowed for each. Valuators are numbered - beginning with 0. Resolutions for all valuators on the device - are returned. For each valuator i on the device, resolutions[i] - returns the current setting of the resolution, - min_resolutions[i] returns the minimum valid setting, and - max_resolutions[i] returns the maximum valid setting. - - When this control is specified, XGetDeviceControl will fail - with a BadMatch error if the specified device has no valuators. - - ChangeDeviceControl: - device: DEVICE - XID: controlId - control: DeviceControl - - where - - DeviceControl: DeviceResolutionControl - => - status: {Success, DeviceBusy, AlreadyGrabbed} +This request returns the current state of the specified device +control. The device control must be supported by the target +server and device or an error will result. + +If the request is successful, a pointer to a generic +DeviceState structure will be returned. The information +returned varies according to the specified control and is +mapped by a structure appropriate for that control. + +GetDeviceControl will fail with a BadValue error if the server +does not support the specified control. It will fail with a +BadMatch error if the device does not support the specified +control. + +Supported device controls and the information returned for them +include: + + DEVICE_RESOLUTION: + [control: CARD16 + length: CARD16 + num_valuators: CARD8 + resolutions: LISTofCARD32 + min_resolutions: LISTofCARD32 + max_resolutions: LISTofCARD32] + +This device control returns a list of valuators and the range +of valid resolutions allowed for each. Valuators are numbered +beginning with 0. Resolutions for all valuators on the device +are returned. For each valuator i on the device, resolutions[i] +returns the current setting of the resolution, +min_resolutions[i] returns the minimum valid setting, and +max_resolutions[i] returns the maximum valid setting. + +When this control is specified, XGetDeviceControl will fail +with a BadMatch error if the specified device has no valuators. + + ChangeDeviceControl: + device: DEVICE + XID: controlId + control: DeviceControl + +where + + DeviceControl: DeviceResolutionControl + => + status: {Success, DeviceBusy, AlreadyGrabbed} Errors: Length, Device, Match, Value - ChangeDeviceControl changes the specifed device control - according to the values specified in the DeviceControl - structure. The device control must be supported by the target - server and device or an error will result. - - The information passed with this request varies according to - the specified control and is mapped by a structure appropriate - for that control. - - ChangeDeviceControl will fail with a BadValue error if the - server does not support the specified control. It will fail - with a BadMatch error if the server supports the specified - control, but the requested device does not. The request will - fail and return a status of DeviceBusy if another client - already has the device open with a device control state that - conflicts with the one specified in the request. It will fail - with a status of AlreadyGrabbed if some other client has - grabbed the specified device. If the request succeeds, Success - is returned. If it fails, the device control is left unchanged. - - Supported device controls and the information specified for - them include: - - DEVICE_RESOLUTION: - [control: CARD16 - length: CARD16 - first_valuator: CARD8 - num_valuators: CARD8 - resolutions: LISTofCARD32] - - This device control changes the resolution of the specified - valuators on the specified extension input device. Valuators - are numbered beginning with zero. Only the valuators in the - range specified by first_valuator and num_valuators are set. A - value of -1 in the resolutions list indicates that the - resolution for this valuator is not to be changed. - num_valuators specifies the number of valuators in the - resolutions list. - - When this control is specified, XChangeDeviceControl will fail - with a BadMatch error if the specified device has no valuators. - If a resolution is specified that is not within the range of - valid values (as returned by XGetDeviceControl) the request - will fail with a BadValue error. If the number of valuators - supported by the device is less than the expression - first_valuator + num_valuators, a BadValue error will result. - - If the request fails for any reason, none of the valuator - resolutions will be changed. - - ChangeDeviceControl causes the server to send a DevicePresence - event to interested clients. +ChangeDeviceControl changes the specifed device control +according to the values specified in the DeviceControl +structure. The device control must be supported by the target +server and device or an error will result. + +The information passed with this request varies according to +the specified control and is mapped by a structure appropriate +for that control. + +ChangeDeviceControl will fail with a BadValue error if the +server does not support the specified control. It will fail +with a BadMatch error if the server supports the specified +control, but the requested device does not. The request will +fail and return a status of DeviceBusy if another client +already has the device open with a device control state that +conflicts with the one specified in the request. It will fail +with a status of AlreadyGrabbed if some other client has +grabbed the specified device. If the request succeeds, Success +is returned. If it fails, the device control is left unchanged. + +Supported device controls and the information specified for +them include: + + DEVICE_RESOLUTION: + [control: CARD16 + length: CARD16 + first_valuator: CARD8 + num_valuators: CARD8 + resolutions: LISTofCARD32] + +This device control changes the resolution of the specified +valuators on the specified extension input device. Valuators +are numbered beginning with zero. Only the valuators in the +range specified by first_valuator and num_valuators are set. A +value of -1 in the resolutions list indicates that the +resolution for this valuator is not to be changed. +num_valuators specifies the number of valuators in the +resolutions list. + +When this control is specified, XChangeDeviceControl will fail +with a BadMatch error if the specified device has no valuators. +If a resolution is specified that is not within the range of +valid values (as returned by XGetDeviceControl) the request +will fail with a BadValue error. If the number of valuators +supported by the device is less than the expression +first_valuator + num_valuators, a BadValue error will result. + +If the request fails for any reason, none of the valuator +resolutions will be changed. + +ChangeDeviceControl causes the server to send a DevicePresence +event to interested clients. 2.7 Selecting Extension Device Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Extension input events are selected using the - SelectExtensionEvent request. +Extension input events are selected using the +SelectExtensionEvent request. - SelectExtensionEvent - interest: LISTofEVENTCLASS - window: WINDOW + SelectExtensionEvent + interest: LISTofEVENTCLASS + window: WINDOW Errors: Window, Class, Access - This request specifies to the server the events within the - specified window which are of interest to the client. As with - the core XSelectInput function, multiple clients can select - input on the same window. - - XSelectExtensionEvent requires a list of event classes. An - event class is a 32-bit number that combines an event type and - device id, and is used to indicate which event a client wishes - to receive and from which device it wishes to receive it. - Macros are provided to obtain event classes from the data - returned by the XOpenDevice request. The names of these macros - correspond to the desired events, i.e. the DeviceKeyPress is - used to obtain the event class for DeviceKeyPress events. The - syntax of the macro invocation is: - DeviceKeyPress (device, event_type, event_class); - device: DEVICE - event_type: INT - event_class: INT - - The value returned in event_type is the value that will be - contained in the event type field of the XDeviceKeyPressEvent - when it is received by the client. The value returned in - event_class is the value that should be passed in making an - XSelectExtensionEvent request to receive DeviceKeyPress events. - - For DeviceButtonPress events, the client may specify whether or - not an implicit passive grab should be done when the button is - pressed. If the client wants to guarantee that it will receive - a DeviceButtonRelease event for each DeviceButtonPress event it - receives, it should specify the DeviceButtonPressGrab event - class as well as the DeviceButtonPress event class. This - restricts the client in that only one client at a time may - request DeviceButtonPress events from the same device and - window if any client specifies this class. - - If any client has specified the DeviceButtonPressGrab class, - any requests by any other client that specify the same device - and window and specify DeviceButtonPress or - DeviceButtonPressGrab will cause an Access error to be - generated. - - If only the DeviceButtonPress class is specified, no implicit - passive grab will be done when a button is pressed on the - device. Multiple clients may use this class to specify the same - device and window combination. - - A client may also specify the DeviceOwnerGrabButton class. If - it has specified both the DeviceButtonPressGrab and the - DeviceOwnerGrabButton classes, implicit passive grabs will - activate with owner_events set to True. If only the - DeviceButtonPressGrab class is specified, implicit passive - grabs will activate with owner_events set to False. - - The client may select DeviceMotion events only when a button is - down. It does this by specifying the event classes - Button1Motion through Button5Motion, or ButtonMotion. An input - device will only support as many button motion classes as it - has buttons. +This request specifies to the server the events within the +specified window which are of interest to the client. As with +the core XSelectInput function, multiple clients can select +input on the same window. + +XSelectExtensionEvent requires a list of event classes. An +event class is a 32-bit number that combines an event type and +device id, and is used to indicate which event a client wishes +to receive and from which device it wishes to receive it. +Macros are provided to obtain event classes from the data +returned by the XOpenDevice request. The names of these macros +correspond to the desired events, i.e. the DeviceKeyPress is +used to obtain the event class for DeviceKeyPress events. The +syntax of the macro invocation is: + + DeviceKeyPress (device, event_type, event_class); + device: DEVICE + event_type: INT + event_class: INT + +The value returned in event_type is the value that will be +contained in the event type field of the XDeviceKeyPressEvent +when it is received by the client. The value returned in +event_class is the value that should be passed in making an +XSelectExtensionEvent request to receive DeviceKeyPress events. + +For DeviceButtonPress events, the client may specify whether or +not an implicit passive grab should be done when the button is +pressed. If the client wants to guarantee that it will receive +a DeviceButtonRelease event for each DeviceButtonPress event it +receives, it should specify the DeviceButtonPressGrab event +class as well as the DeviceButtonPress event class. This +restricts the client in that only one client at a time may +request DeviceButtonPress events from the same device and +window if any client specifies this class. + +If any client has specified the DeviceButtonPressGrab class, +any requests by any other client that specify the same device +and window and specify DeviceButtonPress or +DeviceButtonPressGrab will cause an Access error to be +generated. + +If only the DeviceButtonPress class is specified, no implicit +passive grab will be done when a button is pressed on the +device. Multiple clients may use this class to specify the same +device and window combination. + +A client may also specify the DeviceOwnerGrabButton class. If +it has specified both the DeviceButtonPressGrab and the +DeviceOwnerGrabButton classes, implicit passive grabs will +activate with owner_events set to True. If only the +DeviceButtonPressGrab class is specified, implicit passive +grabs will activate with owner_events set to False. + +The client may select DeviceMotion events only when a button is +down. It does this by specifying the event classes +Button1Motion through Button5Motion, or ButtonMotion. An input +device will only support as many button motion classes as it +has buttons. 2.8 Determining Selected Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To determine which extension events are currently selected from - a given window, use GetSelectedExtensionEvents. +To determine which extension events are currently selected from +a given window, use GetSelectedExtensionEvents. - GetSelectedExtensionEvents - window: WINDOW - => - this-client: LISTofEVENTCLASS - all-clients: LISTofEVENTCLASS + GetSelectedExtensionEvents + window: WINDOW + => + this-client: LISTofEVENTCLASS + all-clients: LISTofEVENTCLASS Errors: Window - This request returns two lists specifying the events selected - on the specified window. One list gives the extension events - selected by this client from the specified window. The other - list gives the extension events selected by all clients from - the specified window. This information is equivalent to that - returned by your-event-mask and all-event-masks in a - GetWindowAttributes request. +This request returns two lists specifying the events selected +on the specified window. One list gives the extension events +selected by this client from the specified window. The other +list gives the extension events selected by all clients from +the specified window. This information is equivalent to that +returned by your-event-mask and all-event-masks in a +GetWindowAttributes request. 2.9 Controlling Event Propagation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Extension events propagate up the window hierarchy in the same - manner as core events. If a window is not interested in an - extension event, it usually propagates to the closest ancestor - that is interested, unless the dont_propagate list prohibits - it. Grabs of extension devices may alter the set of windows - that receive a particular extension event. +Extension events propagate up the window hierarchy in the same +manner as core events. If a window is not interested in an +extension event, it usually propagates to the closest ancestor +that is interested, unless the dont_propagate list prohibits +it. Grabs of extension devices may alter the set of windows +that receive a particular extension event. - Client programs may control extension event propagation through - the use of the following two requests. +Client programs may control extension event propagation through +the use of the following two requests. - XChangeDeviceDontPropagateList adds an event to or deletes an - event from the do_not_propagate list of extension events for - the specified window. This list is maintained for the life of - the window, and is not altered if the client terminates. +XChangeDeviceDontPropagateList adds an event to or deletes an +event from the do_not_propagate list of extension events for +the specified window. This list is maintained for the life of +the window, and is not altered if the client terminates. - ChangeDeviceDontPropagateList - window: WINDOW - eventclass: LISTofEVENTCLASS - mode: {AddToList, DeleteFromList} + ChangeDeviceDontPropagateList + window: WINDOW + eventclass: LISTofEVENTCLASS + mode: {AddToList, DeleteFromList} Errors: Window, Class, Mode - This function modifies the list specifying the events that are - not propagated to the ancestors of the specified window. You - may use the modes AddToList or DeleteFromList. +This function modifies the list specifying the events that are +not propagated to the ancestors of the specified window. You +may use the modes AddToList or DeleteFromList. - GetDeviceDontPropagateList - window: WINDOW - => - dont-propagate-list: LISTofEVENTCLASS + GetDeviceDontPropagateList + window: WINDOW + => + dont-propagate-list: LISTofEVENTCLASS Errors: Window - This function returns a list specifying the events that are not - propagated to the ancestors of the specified window. +This function returns a list specifying the events that are not +propagated to the ancestors of the specified window. 2.10 Sending Extension Events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - One client program may send an event to another via the - XSendExtensionEvent function. +One client program may send an event to another via the +XSendExtensionEvent function. - The event in the XEvent structure must be one of the events - defined by the input extension, 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 sequence number in the event correctly. +The event in the XEvent structure must be one of the events +defined by the input extension, 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 sequence number in the event correctly. - XSendExtensionEvent returns zero if the conversion-to-wire - protocol failed, otherwise it returns nonzero. +XSendExtensionEvent returns zero if the conversion-to-wire +protocol failed, otherwise it returns nonzero. - SendExtensionEvent - device: DEVICE - destination: WINDOW - propagate: BOOL - eventclass: LISTofEVENTCLASS - event: XEVENT + SendExtensionEvent + device: DEVICE + destination: WINDOW + propagate: BOOL + eventclass: LISTofEVENTCLASS + event: XEVENT Errors: Device, Value, Class, Window 2.11 Getting Motion History +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - GetDeviceMotionEvents - device: DEVICE - start, stop: TIMESTAMP or CurrentTime - => - nevents_return: CARD32 - mode_return: {Absolute, Relative} - axis_count_return: CARD8 - events: LISTofDEVICETIMECOORD + GetDeviceMotionEvents + device: DEVICE + start, stop: TIMESTAMP or CurrentTime + => + nevents_return: CARD32 + mode_return: {Absolute, Relative} + axis_count_return: CARD8 + events: LISTofDEVICETIMECOORD - where +where - DEVICETIMECOORD: - [data: LISTofINT32 - time: TIMESTAMP] + DEVICETIMECOORD: + [data: LISTofINT32 + time: TIMESTAMP] Errors: Device, Match - This request returns all positions in the device's motion - history buffer that fall between the specified start and stop - times inclusive. If the start time is in the future, or is - later than the stop time, no positions are returned. - - The data field of the DEVICETIMECOORD structure is a sequence - of data items. Each item is of type INT32, and there is one - data item per axis of motion reported by the device. The number - of axes reported by the device is returned in the axis_count - variable. - - The value of the data items depends on the mode of the device, - which is returned in the mode variable. If the mode is - Absolute, the data items are the raw values generated by the - device. These may be scaled by the client program using the - maximum values that the device can generate for each axis of - motion that it reports. The maximum and minimum values for each - axis are reported by the ListInputDevices request. - - If the mode is Relative, the data items are the relative values - generated by the device. The client program must choose an - initial position for the device and maintain a current position - by accumulating these relative values. +This request returns all positions in the device's motion +history buffer that fall between the specified start and stop +times inclusive. If the start time is in the future, or is +later than the stop time, no positions are returned. + +The data field of the DEVICETIMECOORD structure is a sequence +of data items. Each item is of type INT32, and there is one +data item per axis of motion reported by the device. The number +of axes reported by the device is returned in the axis_count +variable. + +The value of the data items depends on the mode of the device, +which is returned in the mode variable. If the mode is +Absolute, the data items are the raw values generated by the +device. These may be scaled by the client program using the +maximum values that the device can generate for each axis of +motion that it reports. The maximum and minimum values for each +axis are reported by the ListInputDevices request. + +If the mode is Relative, the data items are the relative values +generated by the device. The client program must choose an +initial position for the device and maintain a current position +by accumulating these relative values. 2.12 Changing The Core Devices - - These requests are provided to change which physical device is - used as the X pointer or X keyboard. These requests are - deprecated in servers supporting XI 1.4 and above, and will - always return a a BadDevice error. - - Using these requests may change the characteristics of the core - devices. The new pointer device may have a different number of - buttons than the old one did, or the new keyboard device may - have a different number of keys or report a different range of - keycodes. Client programs may be running that depend on those - characteristics. For example, a client program could allocate - an array based on the number of buttons on the pointer device, - and then use the button numbers received in button events as - indicies into that array. Changing the core devices could cause - such client programs to behave improperly or abnormally - terminate. - - These requests change the X keyboard or X pointer device and - generate an ChangeDeviceNotify event and a MappingNotify event. - The ChangeDeviceNotify event is sent only to those clients that - have expressed an interest in receiving that event via the - XSelectExtensionEvent request. The specified device becomes the - new X keyboard or X pointer device. The location of the core - device does not change as a result of this request. - - These requests fail and return AlreadyGrabbed if either the - specified device or the core device it would replace are - grabbed by some other client. They fail and return GrabFrozen - if either device is frozen by the active grab of another - client. - - These requests fail with a BadDevice error if the specified - device is invalid, or has not previously been opened via - OpenDevice. To change the X keyboard device, use the - ChangeKeyboardDevice request. The specified device must support - input class Keys (as reported in the ListInputDevices request) - or the request will fail with a BadMatch error. Once the device - has successfully replaced one of the core devices, it is - treated as a core device until it is in turn replaced by - another ChangeDevice request, or until the server terminates. - The termination of the client that changed the device will not - cause it to change back. Attempts to use the CloseDevice - request to close the new core device will fail with a BadDevice - error. - - The focus state of the new keyboard is the same as the focus - state of the old X keyboard. If the new keyboard was not - initialized with a FocusRec, one is added by the - ChangeKeyboardDevice request. The X keyboard is assumed to have - a KbdFeedbackClassRec. If the device was initialized without a - KbdFeedbackClassRec, one will be added by this request. The - KbdFeedbackClassRec will specify a null routine as the control - procedure and the bell procedure. - - ChangeKeyboardDevice - device: DEVICE - => - status: Success, AlreadyGrabbed, Frozen +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These requests are provided to change which physical device is +used as the X pointer or X keyboard. These requests are +deprecated in servers supporting XI 1.4 and above, and will +always return a a BadDevice error. + +Using these requests may change the characteristics of the core +devices. The new pointer device may have a different number of +buttons than the old one did, or the new keyboard device may +have a different number of keys or report a different range of +keycodes. Client programs may be running that depend on those +characteristics. For example, a client program could allocate +an array based on the number of buttons on the pointer device, +and then use the button numbers received in button events as +indicies into that array. Changing the core devices could cause +such client programs to behave improperly or abnormally +terminate. + +These requests change the X keyboard or X pointer device and +generate an ChangeDeviceNotify event and a MappingNotify event. +The ChangeDeviceNotify event is sent only to those clients that +have expressed an interest in receiving that event via the +XSelectExtensionEvent request. The specified device becomes the +new X keyboard or X pointer device. The location of the core +device does not change as a result of this request. + +These requests fail and return AlreadyGrabbed if either the +specified device or the core device it would replace are +grabbed by some other client. They fail and return GrabFrozen +if either device is frozen by the active grab of another +client. + +These requests fail with a BadDevice error if the specified +device is invalid, or has not previously been opened via +OpenDevice. To change the X keyboard device, use the +ChangeKeyboardDevice request. The specified device must support +input class Keys (as reported in the ListInputDevices request) +or the request will fail with a BadMatch error. Once the device +has successfully replaced one of the core devices, it is +treated as a core device until it is in turn replaced by +another ChangeDevice request, or until the server terminates. +The termination of the client that changed the device will not +cause it to change back. Attempts to use the CloseDevice +request to close the new core device will fail with a BadDevice +error. + +The focus state of the new keyboard is the same as the focus +state of the old X keyboard. If the new keyboard was not +initialized with a FocusRec, one is added by the +ChangeKeyboardDevice request. The X keyboard is assumed to have +a KbdFeedbackClassRec. If the device was initialized without a +KbdFeedbackClassRec, one will be added by this request. The +KbdFeedbackClassRec will specify a null routine as the control +procedure and the bell procedure. + + ChangeKeyboardDevice + device: DEVICE + => + status: Success, AlreadyGrabbed, Frozen Errors: Device, Match - To change the X pointer device, use the ChangePointerDevice - request. The specified device must support input class - Valuators (as reported in the ListInputDevices request) or the - request will fail with a BadMatch error. The valuators to be - used as the x- and y-axes of the pointer device must be - specified. Data from other valuators on the device will be - ignored. - - The X pointer device does not contain a FocusRec. If the new - pointer was initialized with a FocusRec, it is freed by the - ChangePointerDevice request. The X pointer is assumed to have a - ButtonClassRec and a PtrFeedbackClassRec. If the device was - initialized without a ButtonClassRec or a PtrFeedbackClassRec, - one will be added by this request. The ButtonClassRec added - will have no buttons, and the PtrFeedbackClassRec will specify - a null routine as the control procedure. - - If the specified device reports absolute positional - information, and the server implementation does not allow such - a device to be used as the X pointer, the request will fail - with a BadDevice error. - - Once the device has successfully replaced one of the core - devices, it is treated as a core device until it is in turn - replaced by another ChangeDevice request, or until the server - terminates. The termination of the client that changed the - device will not cause it to change back. Attempts to use the - CloseDevice request to close the new core device will fail with - a BadDevice error. - - ChangePointerDevice - device: DEVICE - xaxis: CARD8 - yaxis: CARD8 - => - status: Success, AlreadyGrabbed, Frozen +To change the X pointer device, use the ChangePointerDevice +request. The specified device must support input class +Valuators (as reported in the ListInputDevices request) or the +request will fail with a BadMatch error. The valuators to be +used as the x- and y-axes of the pointer device must be +specified. Data from other valuators on the device will be +ignored. + +The X pointer device does not contain a FocusRec. If the new +pointer was initialized with a FocusRec, it is freed by the +ChangePointerDevice request. The X pointer is assumed to have a +ButtonClassRec and a PtrFeedbackClassRec. If the device was +initialized without a ButtonClassRec or a PtrFeedbackClassRec, +one will be added by this request. The ButtonClassRec added +will have no buttons, and the PtrFeedbackClassRec will specify +a null routine as the control procedure. + +If the specified device reports absolute positional +information, and the server implementation does not allow such +a device to be used as the X pointer, the request will fail +with a BadDevice error. + +Once the device has successfully replaced one of the core +devices, it is treated as a core device until it is in turn +replaced by another ChangeDevice request, or until the server +terminates. The termination of the client that changed the +device will not cause it to change back. Attempts to use the +CloseDevice request to close the new core device will fail with +a BadDevice error. + + ChangePointerDevice + device: DEVICE + xaxis: CARD8 + yaxis: CARD8 + => + status: Success, AlreadyGrabbed, Frozen Errors: Device, Match 2.12 Event Synchronization And Core Grabs - - Implementation of the input extension requires an extension of - the meaning of event synchronization for the core grab - requests. This is necessary in order to allow window managers - to freeze all input devices with a single request. - - The core grab requests require a pointer_mode and keyboard_mode - argument. The meaning of these modes is changed by the input - extension. For the XGrabPointer and XGrabButton requests, - pointer_mode controls synchronization of the pointer device, - and keyboard_mode controls the synchronization of all other - input devices. For the XGrabKeyboard and XGrabKey requests, - pointer_mode controls the synchronization of all input devices - except the X keyboard, while keyboard_mode controls the - synchronization of the keyboard. When using one of the core - grab requests, the synchronization of extension devices is - controlled by the mode specified for the device not being - grabbed. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Implementation of the input extension requires an extension of +the meaning of event synchronization for the core grab +requests. This is necessary in order to allow window managers +to freeze all input devices with a single request. + +The core grab requests require a pointer_mode and keyboard_mode +argument. The meaning of these modes is changed by the input +extension. For the XGrabPointer and XGrabButton requests, +pointer_mode controls synchronization of the pointer device, +and keyboard_mode controls the synchronization of all other +input devices. For the XGrabKeyboard and XGrabKey requests, +pointer_mode controls the synchronization of all input devices +except the X keyboard, while keyboard_mode controls the +synchronization of the keyboard. When using one of the core +grab requests, the synchronization of extension devices is +controlled by the mode specified for the device not being +grabbed. 2.13 Extension Active Grabs +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Active grabs of extension devices are supported via the +GrabDevice request in the same way that core devices are +grabbed using the core GrabKeyboard request, except that a +Device is passed as a function parameter. A list of events that +the client wishes to receive is also passed. The UngrabDevice +request allows a previous active grab for an extension device +to be released. - Active grabs of extension devices are supported via the - GrabDevice request in the same way that core devices are - grabbed using the core GrabKeyboard request, except that a - Device is passed as a function parameter. A list of events that - the client wishes to receive is also passed. The UngrabDevice - request allows a previous active grab for an extension device - to be released. - - To grab an extension device, use the GrabDevice request. The - device must have previously been opened using the OpenDevice - request. - - GrabDevice - device: DEVICE - grab-window: WINDOW - owner-events: BOOL - event-list: LISTofEVENTCLASS - this-device-mode: {Synchronous, Asynchronous} - other-device-mode: {Synchronous, Asynchronous} - time:TIMESTAMP or CurrentTime - => - status: Success, AlreadyGrabbed, Frozen, - InvalidTime, NotViewable +To grab an extension device, use the GrabDevice request. The +device must have previously been opened using the OpenDevice +request. + + GrabDevice + device: DEVICE + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} + time:TIMESTAMP or CurrentTime + => + status: Success, AlreadyGrabbed, Frozen, + InvalidTime, NotViewable Errors: Device, Window, Value - This request actively grabs control of the specified input - device. Further input events from this device are reported only - to the grabbing client. This request overrides any previous - active grab by this client for this device. - - The event-list parameter is a pointer to a list of event - classes. These are used to indicate which events the client - wishes to receive while the device is grabbed. Only event - classes obtained from the grabbed device are valid. - - If owner-events is False, input events generated from this - device are reported with respect to grab-window, and are only - reported if selected by being included in the event-list. If - owner-events is True, then if a generated event would normally - be reported to this client, it is reported normally, otherwise - the event is reported with respect to the grab-window, and is - only reported if selected by being included in the event-list. - For either value of owner-events, unreported events are - discarded. - - If this-device-mode is Asynchronous, device event processing - continues normally. If the device is currently frozen by this - client, then processing of device events is resumed. If - this-device-mode is Synchronous, the state of the grabbed - device (as seen by means of the protocol) appears to freeze, - and no further device events are generated by the server until - the grabbing client issues a releasing AllowDeviceEvents - request or until the device grab is released. Actual device - input events are not lost while the device is frozen; they are - simply queued for later processing. - - If other-device-mode is Asynchronous, event processing is - unaffected by activation of the grab. If other-device-mode is - Synchronous, the state of all input devices except the grabbed - one (as seen by means of the protocol) appears to freeze, and - no further events are generated by the server until the - grabbing client issues a releasing AllowDeviceEvents request or - until the device grab is released. Actual events are not lost - while the devices are frozen; they are simply queued for later - processing. - - This request generates DeviceFocusIn and DeviceFocusOut events. - - This request fails and returns: +This request actively grabs control of the specified input +device. Further input events from this device are reported only +to the grabbing client. This request overrides any previous +active grab by this client for this device. + +The event-list parameter is a pointer to a list of event +classes. These are used to indicate which events the client +wishes to receive while the device is grabbed. Only event +classes obtained from the grabbed device are valid. + +If owner-events is False, input events generated from this +device are reported with respect to grab-window, and are only +reported if selected by being included in the event-list. If +owner-events is True, then if a generated event would normally +be reported to this client, it is reported normally, otherwise +the event is reported with respect to the grab-window, and is +only reported if selected by being included in the event-list. +For either value of owner-events, unreported events are +discarded. + +If this-device-mode is Asynchronous, device event processing +continues normally. If the device is currently frozen by this +client, then processing of device events is resumed. If +this-device-mode is Synchronous, the state of the grabbed +device (as seen by means of the protocol) appears to freeze, +and no further device events are generated by the server until +the grabbing client issues a releasing AllowDeviceEvents +request or until the device grab is released. Actual device +input events are not lost while the device is frozen; they are +simply queued for later processing. + +If other-device-mode is Asynchronous, event processing is +unaffected by activation of the grab. If other-device-mode is +Synchronous, the state of all input devices except the grabbed +one (as seen by means of the protocol) appears to freeze, and +no further events are generated by the server until the +grabbing client issues a releasing AllowDeviceEvents request or +until the device grab is released. Actual events are not lost +while the devices are frozen; they are simply queued for later +processing. + +This request generates DeviceFocusIn and DeviceFocusOut events. + +This request fails and returns: AlreadyGrabbed If the device is actively grabbed by some other client. @@ -1144,59 +1168,61 @@ If the device is frozen by an active grab of another client. - If a grabbed device is closed by a client while an active grab - by that client is in effect, that active grab will be released. - Any passive grabs established by that client will be released. - If the device is frozen only by an active grab of the - requesting client, it is thawed. +If a grabbed device is closed by a client while an active grab +by that client is in effect, that active grab will be released. +Any passive grabs established by that client will be released. +If the device is frozen only by an active grab of the +requesting client, it is thawed. - To release a grab of an extension device, use UngrabDevice. +To release a grab of an extension device, use UngrabDevice. - UngrabDevice - device: DEVICE - time: TIMESTAMP or CurrentTime + UngrabDevice + device: DEVICE + time: TIMESTAMP or CurrentTime Errors: Device - This request releases the device if this client has it actively - grabbed (from either GrabDevice or GrabDeviceKey) and releases - any queued events. If any devices were frozen by the grab, - UngrabDevice thaws them. The request has no effect if the - specified time is earlier than the last-device-grab time or is - later than the current server time. +This request releases the device if this client has it actively +grabbed (from either GrabDevice or GrabDeviceKey) and releases +any queued events. If any devices were frozen by the grab, +UngrabDevice thaws them. The request has no effect if the +specified time is earlier than the last-device-grab time or is +later than the current server time. - This request generates DeviceFocusIn and DeviceFocusOut events. +This request generates DeviceFocusIn and DeviceFocusOut events. - An UngrabDevice is performed automatically if the event window - for an active device grab becomes not viewable. +An UngrabDevice is performed automatically if the event window +for an active device grab becomes not viewable. 2.14 Passively Grabbing A Key - - Passive grabs of buttons and keys on extension devices are - supported via the GrabDeviceButton and GrabDeviceKey requests. - These passive grabs are released via the UngrabDeviceKey and - UngrabDeviceButton requests. - - To passively grab a single key on an extension device, use - GrabDeviceKey. That device must have previously been opened - using the OpenDevice request. - - GrabDeviceKey - device: DEVICE - keycode: KEYCODE or AnyKey - modifiers: SETofKEYMASK or AnyModifier - modifier-device: DEVICE or NULL - grab-window: WINDOW - owner-events: BOOL - event-list: LISTofEVENTCLASS - this-device-mode: {Synchronous, Asynchronous} - other-device-mode: {Synchronous, Asynchronous} +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Passive grabs of buttons and keys on extension devices are +supported via the GrabDeviceButton and GrabDeviceKey requests. +These passive grabs are released via the UngrabDeviceKey and +UngrabDeviceButton requests. + +To passively grab a single key on an extension device, use +GrabDeviceKey. That device must have previously been opened +using the OpenDevice request. + + GrabDeviceKey + device: DEVICE + keycode: KEYCODE or AnyKey + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} Errors: Device, Match, Access, Window, Value - This request is analogous to the core GrabKey request. It - establishes a passive grab on a device. Consequently, in the - future: +This request is analogous to the core GrabKey request. It +establishes a passive grab on a device. Consequently, in the +future: + * IF the device is not grabbed and the specified key, which itself can be a modifier key, is logically pressed when the specified modifier keys logically are down on the specified @@ -1212,202 +1238,197 @@ was pressed (as transmitted in the DeviceKeyPress event), and the DeviceKeyPress event is reported. - The interpretation of the remaining arguments is as for - GrabDevice. The active grab is terminated automatically when - logical state of the device has the specified key released - (independent of the logical state of the modifier keys). - - Note that the logical state of a device (as seen by means of - the X protocol) may lag the physical state if device event - processing is frozen. - - A modifier of AnyModifier is equivalent to issuing the request - for all possible modifier combinations (including the - combination of no modifiers). It is not required that all - modifiers specified have currently assigned keycodes. A key of - AnyKey is equivalent to issuing the request for all possible - keycodes. Otherwise, the key must be in the range specified by - min-keycode and max-keycode in the ListInputDevices request. If - it is not within that range, GrabDeviceKey generates a Value - error. - - NULL may be passed for the modifier_device. If the - modifier_device is NULL, the core X keyboard is used as the - modifier_device. - - An Access error is generated if some other client has issued a - GrabDeviceKey with the same device and key combination on the - same window. When using AnyModifier or AnyKey, the request - fails completely and the X server generates a Access error and - no grabs are established if there is a conflicting grab for any - combination. - - This request cannot be used to grab a key on the X keyboard - device. The core GrabKey request should be used for that - purpose. - - To release a passive grab of a single key on an extension - device, use UngrabDeviceKey. - - UngrabDeviceKey - device: DEVICE - keycode: KEYCODE or AnyKey - modifiers: SETofKEYMASK or AnyModifier - modifier-device: DEVICE or NULL - grab-window: WINDOW +The interpretation of the remaining arguments is as for +GrabDevice. The active grab is terminated automatically when +logical state of the device has the specified key released +(independent of the logical state of the modifier keys). + +Note that the logical state of a device (as seen by means of +the X protocol) may lag the physical state if device event +processing is frozen. + +A modifier of AnyModifier is equivalent to issuing the request +for all possible modifier combinations (including the +combination of no modifiers). It is not required that all +modifiers specified have currently assigned keycodes. A key of +AnyKey is equivalent to issuing the request for all possible +keycodes. Otherwise, the key must be in the range specified by +min-keycode and max-keycode in the ListInputDevices request. If +it is not within that range, GrabDeviceKey generates a Value +error. + +NULL may be passed for the modifier_device. If the +modifier_device is NULL, the core X keyboard is used as the +modifier_device. + +An Access error is generated if some other client has issued a +GrabDeviceKey with the same device and key combination on the +same window. When using AnyModifier or AnyKey, the request +fails completely and the X server generates a Access error and +no grabs are established if there is a conflicting grab for any +combination. + +This request cannot be used to grab a key on the X keyboard +device. The core GrabKey request should be used for that +purpose. + +To release a passive grab of a single key on an extension +device, use UngrabDeviceKey. + + UngrabDeviceKey + device: DEVICE + keycode: KEYCODE or AnyKey + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW Errors: Device, Match, Window, Value, Alloc - This request is analogous to the core UngrabKey request. It - releases the key combination on the specified window if it was - grabbed by this client. A modifier of AnyModifier is equivalent - to issuing the request for all possible modifier combinations - (including the combination of no modifiers). A key of AnyKey is - equivalent to issuing the request for all possible keycodes. - This request has no effect on an active grab. +This request is analogous to the core UngrabKey request. It +releases the key combination on the specified window if it was +grabbed by this client. A modifier of AnyModifier is equivalent +to issuing the request for all possible modifier combinations +(including the combination of no modifiers). A key of AnyKey is +equivalent to issuing the request for all possible keycodes. +This request has no effect on an active grab. - NULL may be passed for the modifier_device. If the - modifier_device is NULL, the core X keyboard is used as the - modifier_device. +NULL may be passed for the modifier_device. If the +modifier_device is NULL, the core X keyboard is used as the +modifier_device. 2.15 Passively Grabbing A Button +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To establish a passive grab for a single button on an extension - device, use GrabDeviceButton. - - GrabDeviceButton - device: DEVICE - button: BUTTON or AnyButton - modifiers: SETofKEYMASK or AnyModifier - modifier-device: DEVICE or NULL - grab-window: WINDOW - owner-events: BOOL - event-list: LISTofEVENTCLASS - this-device-mode: {Synchronous, Asynchr - onous} - other-device-mode: {Synchronous, Asynch - ronous} +To establish a passive grab for a single button on an extension +device, use GrabDeviceButton. + + GrabDeviceButton + device: DEVICE + button: BUTTON or AnyButton + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} Errors: Device, Match, Window, Access, Value - This request is analogous to the core GrabButton request. It - establishes an explicit passive grab for a button on an - extension input device. Since the server does not track - extension devices, no cursor is specified with this request. - For the same reason, there is no confine-to parameter. The - device must have previously been opened using the OpenDevice - request. - - The GrabDeviceButton request establishes a passive grab on a - device. Consequently, in the future, - - • - IF the device is not grabbed and the specified button is - logically pressed when the specified modifier keys - logically are down (and no other buttons or modifier - keys are down), - - • - AND the grab window contains the device, - - • - AND a passive grab on the same device and button/ key - combination does not exist on any ancestor of the grab - window, - - • - THEN the device is actively grabbed, as for GrabDevice, - the last-grab time is set to the time at which the - button was pressed (as transmitted in the - DeviceButtonPress event), and the DeviceButtonPress - event is reported. - - The interpretation of the remaining arguments is as for - GrabDevice. The active grab is terminated automatically when - logical state of the device has all buttons released - (independent of the logical state of the modifier keys). - - Note that the logical state of a device (as seen by means of - the X protocol) may lag the physical state if device event - processing is frozen. - - A modifier of AnyModifier is equivalent to issuing the request - for all possible modifier combinations (including the - combination of no modifiers). It is not required that all - modifiers specified have currently assigned keycodes. A button - of AnyButton is equivalent to issuing the request for all - possible buttons. It is not required that the specified button - be assigned to a physical button. - - NULL may be passed for the modifier_device. If the - modifier_device is NULL, the core X keyboard is used as the - modifier_device. - - An Access error is generated if some other client has issued a - GrabDeviceButton with the same device and button combination on - the same window. When using AnyModifier or AnyButton, the - request fails completely and the X server generates a Access - error and no grabs are established if there is a conflicting - grab for any combination. The request has no effect on an - active grab. - - This request cannot be used to grab a button on the X pointer - device. The core GrabButton request should be used for that - purpose. - - To release a passive grab of a button on an extension device, - use UngrabDeviceButton. - - UngrabDeviceButton - device: DEVICE - button: BUTTON or AnyButton - modifiers: SETofKEYMASK or AnyModifier - modifier-device: DEVICE or NULL - grab-window: WINDOW +This request is analogous to the core GrabButton request. It +establishes an explicit passive grab for a button on an +extension input device. Since the server does not track +extension devices, no cursor is specified with this request. +For the same reason, there is no confine-to parameter. The +device must have previously been opened using the OpenDevice +request. + +The GrabDeviceButton request establishes a passive grab on a +device. Consequently, in the future, + + * IF the device is not grabbed and the specified button is + logically pressed when the specified modifier keys + logically are down (and no other buttons or modifier + keys are down), + + * AND the grab window contains the device, + + * AND a passive grab on the same device and button/ key + combination does not exist on any ancestor of the grab + window, + + * THEN the device is actively grabbed, as for GrabDevice, + the last-grab time is set to the time at which the + button was pressed (as transmitted in the + DeviceButtonPress event), and the DeviceButtonPress + event is reported. + +The interpretation of the remaining arguments is as for +GrabDevice. The active grab is terminated automatically when +logical state of the device has all buttons released +(independent of the logical state of the modifier keys). + +Note that the logical state of a device (as seen by means of +the X protocol) may lag the physical state if device event +processing is frozen. + +A modifier of AnyModifier is equivalent to issuing the request +for all possible modifier combinations (including the +combination of no modifiers). It is not required that all +modifiers specified have currently assigned keycodes. A button +of AnyButton is equivalent to issuing the request for all +possible buttons. It is not required that the specified button +be assigned to a physical button. + +NULL may be passed for the modifier_device. If the +modifier_device is NULL, the core X keyboard is used as the +modifier_device. + +An Access error is generated if some other client has issued a +GrabDeviceButton with the same device and button combination on +the same window. When using AnyModifier or AnyButton, the +request fails completely and the X server generates a Access +error and no grabs are established if there is a conflicting +grab for any combination. The request has no effect on an +active grab. + +This request cannot be used to grab a button on the X pointer +device. The core GrabButton request should be used for that +purpose. + +To release a passive grab of a button on an extension device, +use UngrabDeviceButton. + + UngrabDeviceButton + device: DEVICE + button: BUTTON or AnyButton + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW Errors: Device, Match, Window, Value, Alloc - This request is analogous to the core UngrabButton request. It - releases the passive button/key combination on the specified - window if it was grabbed by the client. A modifiers of - AnyModifier is equivalent to issuing the request for all - possible modifier combinations (including the combination of no - modifiers). A button of AnyButton is equivalent to issuing the - request for all possible buttons. This request has no effect on - an active grab. The device must have previously been opened - using the OpenDevice request otherwise a Device error will be - generated. - - NULL may be passed for the modifier_device. If the - modifier_device is NULL, the core X keyboard is used as the - modifier_device. - - This request cannot be used to ungrab a button on the X pointer - device. The core UngrabButton request should be used for that - purpose. +This request is analogous to the core UngrabButton request. It +releases the passive button/key combination on the specified +window if it was grabbed by the client. A modifiers of +AnyModifier is equivalent to issuing the request for all +possible modifier combinations (including the combination of no +modifiers). A button of AnyButton is equivalent to issuing the +request for all possible buttons. This request has no effect on +an active grab. The device must have previously been opened +using the OpenDevice request otherwise a Device error will be +generated. + +NULL may be passed for the modifier_device. If the +modifier_device is NULL, the core X keyboard is used as the +modifier_device. + +This request cannot be used to ungrab a button on the X pointer +device. The core UngrabButton request should be used for that +purpose. 2.16 Thawing A Device +~~~~~~~~~~~~~~~~~~~~~ - To allow further events to be processed when a device has been - frozen, use AllowDeviceEvents. +To allow further events to be processed when a device has been +frozen, use AllowDeviceEvents. - AllowDeviceEvents - device: DEVICE - event-mode: {AsyncThisDevice, SyncThisD - evice, AsyncOtherDevices, - ReplayThisdevice, AsyncAll, or SyncAll} - time:TIMESTAMP or CurrentTime + AllowDeviceEvents + device: DEVICE + event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices, + ReplayThisdevice, AsyncAll, or SyncAll} + time:TIMESTAMP or CurrentTime Errors: Device, Value - The AllowDeviceEvents request releases some queued events if - the client has caused a device to freeze. The request has no - effect if the specified time is earlier than the last-grab time - of the most recent active grab for the client, or if the - specified time is later than the current X server time. +The AllowDeviceEvents request releases some queued events if +the client has caused a device to freeze. The request has no +effect if the specified time is earlier than the last-grab time +of the most recent active grab for the client, or if the +specified time is later than the current X server time. - The following describes the processing that occurs depending on - what constant you pass to the event-mode argument: +The following describes the processing that occurs depending on +what constant you pass to the event-mode argument: * If the specified device is frozen by the client, event processing for that device continues as usual. If the @@ -1469,66 +1490,67 @@ AsyncAll has no effect unless all devices are frozen by the client. - AsyncThisDevice, SyncThisDevice, and ReplayThisDevice - have no effect on the processing of events from the - remaining devices. AsyncOtherDevices has no effect on - the processing of events from the specified device. When - the event_mode is SyncAll or AsyncAll, the device - parameter is ignored. - - It is possible for several grabs of different devices - (by the same or different clients) to be active - simultaneously. If a device is frozen on behalf of any - grab, no event processing is performed for the device. - It is possible for a single device to be frozen because - of several grabs. In this case, the freeze must be - released on behalf of each grab before events can again - be processed. +AsyncThisDevice, SyncThisDevice, and ReplayThisDevice +have no effect on the processing of events from the +remaining devices. AsyncOtherDevices has no effect on +the processing of events from the specified device. When +the event_mode is SyncAll or AsyncAll, the device +parameter is ignored. + +It is possible for several grabs of different devices +(by the same or different clients) to be active +simultaneously. If a device is frozen on behalf of any +grab, no event processing is performed for the device. +It is possible for a single device to be frozen because +of several grabs. In this case, the freeze must be +released on behalf of each grab before events can again +be processed. 2.17 Controlling Device Focus +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - The current focus window for an extension input device can be - determined using the GetDeviceFocus request. Extension devices - are focused using the SetDeviceFocus request in the same way - that the keyboard is focused using the SetInputFocus request, - except that a device is specified as part of the request. One - additional focus state, FollowKeyboard, is provided for - extension devices. +The current focus window for an extension input device can be +determined using the GetDeviceFocus request. Extension devices +are focused using the SetDeviceFocus request in the same way +that the keyboard is focused using the SetInputFocus request, +except that a device is specified as part of the request. One +additional focus state, FollowKeyboard, is provided for +extension devices. - To get the current focus state, revert state, and focus time of - an extension device, use GetDeviceFocus. +To get the current focus state, revert state, and focus time of +an extension device, use GetDeviceFocus. - GetDeviceFocus - device: DEVICE - => - focus: WINDOW, PointerRoot, FollowKeyboard, or None - revert-to: Parent, PointerRoot, FollowKeyboard, or None - focus-time: TIMESTAMP + GetDeviceFocus + device: DEVICE + => + focus: WINDOW, PointerRoot, FollowKeyboard, or None + revert-to: Parent, PointerRoot, FollowKeyboard, or None + focus-time: TIMESTAMP Errors: Device, Match - This request returns the current focus state, revert-to state, - and last-focus-time of an extension device. +This request returns the current focus state, revert-to state, +and last-focus-time of an extension device. - To set the focus of an extension device, use SetDeviceFocus. +To set the focus of an extension device, use SetDeviceFocus. - SetDeviceFocus - device: DEVICE - focus: WINDOW, PointerRoot, FollowKeyboard, or None - revert-to: Parent, PointerRoot, FollowKeyboard, or None - focus-time: TIMESTAMP + SetDeviceFocus + device: DEVICE + focus: WINDOW, PointerRoot, FollowKeyboard, or None + revert-to: Parent, PointerRoot, FollowKeyboard, or None + focus-time: TIMESTAMP Errors: Device, Window, Value, Match - This request changes the focus for an extension input device - and the last-focus-change-time. The request has no effect if - the specified time is earlier than the last-focus-change-time - or is later than the current X server time. Otherwise, the - last-focus-change-time is set to the specified time, with - CurrentTime replaced by the current server time. +This request changes the focus for an extension input device +and the last-focus-change-time. The request has no effect if +the specified time is earlier than the last-focus-change-time +or is later than the current X server time. Otherwise, the +last-focus-change-time is set to the specified time, with +CurrentTime replaced by the current server time. - The action taken by the server when this request is requested - depends on the value of the focus argument: +The action taken by the server when this request is requested +depends on the value of the focus argument: * If the focus argument is None, all input events from this device will be discarded until a new focus window @@ -1549,7 +1571,6 @@ * If you assign FollowKeyboard to the focus argument, the focus window is dynamically taken to be the same as the focus of the X keyboard at each input event. - The specified focus window must be viewable at the time of the request (else a Match error). If the focus window later becomes not viewable, the X server evaluates the @@ -1564,973 +1585,992 @@ RevertToFollowKeyboard, or RevertToNone to the revert-to argument, the focus reverts to that value. - When the focus reverts, the X server generates DeviceFocusIn - and DeviceFocusOut events, but the last-focus-change time is - not affected. +When the focus reverts, the X server generates DeviceFocusIn +and DeviceFocusOut events, but the last-focus-change time is +not affected. - This request causes the X server to generate DeviceFocusIn and - DeviceFocusOut events. +This request causes the X server to generate DeviceFocusIn and +DeviceFocusOut events. 2.18 Controlling Device Feedback +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To get the settings of feedbacks on an extension device, use - GetFeedbackControl. This request provides functionality - equivalent to the core GetKeyboardControl and GetPointerControl - functions. It also provides a way to control displays - associated with an input device that are capable of displaying - an integer or string. - - GetFeedbackControl - device: DEVICE - => - num_feedbacks_return: CARD16 - return_value: LISTofFEEDBACKSTATE - - where - - FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState, - IntegerFeedbackState, StringFeedbackState, - BellFeedbackState, LedFeedbackState} - - Feedbacks are reported by class. Those feedbacks that are - reported for the core keyboard device are in class KbdFeedback, - and are returned in the KbdFeedbackState structure. The members - of that structure are as follows: - - CLASS Kbd: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - key_click_percent: CARD8 - bell_percent: CARD8 - bell_pitch: CARD16 - bell_duration: CARD16 - led_value: BITMASK - global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff} - auto_repeats: LISTofCARD8] - - Those feedbacks that are equivalent to those reported for the - core pointer are in feedback class PtrFeedback and are reported - in the PtrFeedbackState structure. The members of that - structure are: - - CLASS Ptr: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - accelNumerator: CARD16 - accelDenominator: CARD16 - threshold: CARD16] - - Some input devices provide a means of displaying an integer. - Those devices will support feedback class IntegerFeedback, - which is reported in the IntegerFeedbackState structure. The - members of that structure are: - - CLASS Integer: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - resolution: CARD32 - min-val: INT32 - max-val: INT32] - - Some input devices provide a means of displaying a string. - Those devices will support feedback class StringFeedback, which - is reported in the StringFeedbackState structure. The members - of that structure are: - - CLASS String: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - max_symbols: CARD16 - num_keysyms_supported: CARD16 - keysyms_supported: LISTofKEYSYM] - - Some input devices contain a bell. Those devices will support - feedback class BellFeedback, which is reported in the - BellFeedbackState structure. The members of that structure are: - - CLASS Bell: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - percent: CARD8 - pitch: CARD16 - duration: CARD16] - - The percent sets the base volume for the bell between 0 (off) - and 100 (loud) inclusive, if possible. Setting to -1 restores - the default. Other negative values generate a Value error. - - The pitch sets the pitch (specified in Hz) of the bell, if - possible. Setting to -1 restores the default. Other negative - values generate a Value error. - - The duration sets the duration (specified in milliseconds) of - the bell, if possible. Setting to -1 restores the default. - Other negative values generate a Value error. - - A bell generator connected with the console but not directly on - the device is treated as if it were part of the device. Some - input devices contain LEDs. Those devices will support feedback - class Led, which is reported in the LedFeedbackState structure. - The members of that structure are: - - CLASS Led: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - led_mask: BITMASK - led_value: BITMASK] - - Each bit in led_mask indicates that the corresponding led is - supported by the feedback. At most 32 LEDs per feedback are - supported. No standard interpretation of LEDs is defined. - - This function will fail with a BadMatch error if the device - specified in the request does not support feedbacks. +To get the settings of feedbacks on an extension device, use +GetFeedbackControl. This request provides functionality +equivalent to the core GetKeyboardControl and GetPointerControl +functions. It also provides a way to control displays +associated with an input device that are capable of displaying +an integer or string. + + GetFeedbackControl + device: DEVICE + => + num_feedbacks_return: CARD16 + return_value: LISTofFEEDBACKSTATE + +where + + FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState, + IntegerFeedbackState, StringFeedbackState, + BellFeedbackState, LedFeedbackState} + +Feedbacks are reported by class. Those feedbacks that are +reported for the core keyboard device are in class KbdFeedback, +and are returned in the KbdFeedbackState structure. The members +of that structure are as follows: + + CLASS Kbd: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + key_click_percent: CARD8 + bell_percent: CARD8 + bell_pitch: CARD16 + bell_duration: CARD16 + led_value: BITMASK + global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff} + auto_repeats: LISTofCARD8] + +Those feedbacks that are equivalent to those reported for the +core pointer are in feedback class PtrFeedback and are reported +in the PtrFeedbackState structure. The members of that +structure are: + + CLASS Ptr: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + accelNumerator: CARD16 + accelDenominator: CARD16 + threshold: CARD16] + +Some input devices provide a means of displaying an integer. +Those devices will support feedback class IntegerFeedback, +which is reported in the IntegerFeedbackState structure. The +members of that structure are: + + CLASS Integer: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + resolution: CARD32 + min-val: INT32 + max-val: INT32] + +Some input devices provide a means of displaying a string. +Those devices will support feedback class StringFeedback, which +is reported in the StringFeedbackState structure. The members +of that structure are: + + CLASS String: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + max_symbols: CARD16 + num_keysyms_supported: CARD16 + keysyms_supported: LISTofKEYSYM] + +Some input devices contain a bell. Those devices will support +feedback class BellFeedback, which is reported in the +BellFeedbackState structure. The members of that structure are: + + CLASS Bell: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + percent: CARD8 + pitch: CARD16 + duration: CARD16] + +The percent sets the base volume for the bell between 0 (off) +and 100 (loud) inclusive, if possible. Setting to -1 restores +the default. Other negative values generate a Value error. + +The pitch sets the pitch (specified in Hz) of the bell, if +possible. Setting to -1 restores the default. Other negative +values generate a Value error. + +The duration sets the duration (specified in milliseconds) of +the bell, if possible. Setting to -1 restores the default. +Other negative values generate a Value error. + +A bell generator connected with the console but not directly on +the device is treated as if it were part of the device. Some +input devices contain LEDs. Those devices will support feedback +class Led, which is reported in the LedFeedbackState structure. +The members of that structure are: + + CLASS Led: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + led_mask: BITMASK + led_value: BITMASK] + +Each bit in led_mask indicates that the corresponding led is +supported by the feedback. At most 32 LEDs per feedback are +supported. No standard interpretation of LEDs is defined. + +This function will fail with a BadMatch error if the device +specified in the request does not support feedbacks. Errors: Device, Match - To change the settings of a feedback on an extension device, - use ChangeFeedbackControl. - - ChangeFeedbackControl - device: DEVICE - feedbackid: CARD8 - value-mask: BITMASK - value: FEEDBACKCONTROL - FEEDBACKCONTROL: {KBDFEEDBACKCONTROL, - PTRFEEDBACKCONTROL, - INTEGERFEEDBACKCONTROL, - STRINGFEEDBACKCONTROL, - BELLFEEDBACKCONTROL, - LEDFEEDBACKCONTROL} +To change the settings of a feedback on an extension device, +use ChangeFeedbackControl. + + ChangeFeedbackControl + device: DEVICE + feedbackid: CARD8 + value-mask: BITMASK + value: FEEDBACKCONTROL + FEEDBACKCONTROL: {KBDFEEDBACKCONTROL, + PTRFEEDBACKCONTROL, + INTEGERFEEDBACKCONTROL, + STRINGFEEDBACKCONTROL, + BELLFEEDBACKCONTROL, + LEDFEEDBACKCONTROL} Errors: Device, Match, Value - Feedback controls are grouped by class. Those feedbacks that - are equivalent to those supported by the core keyboard are - controlled by feedback class KbdFeedbackClass using the - KbdFeedbackControl structure. The members of that structure - are: - - KBDFEEDBACKCTL - [class: CARD8 - length: CARD16 - feedback id: CARD8 - key_click_percent: INT8 - bell_percent: INT8 - bell_pitch: INT16 - bell_duration: INT16 - led_mask: INT32 - led_value: INT32 - key: KEYCODE - auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff, - AutoRepeatModeDefault}] - - The key_click_percent sets the volume for key clicks between 0 - (off) and 100 (loud) inclusive, if possible. Setting to -1 - restores the default. Other negative values generate a Value - error. - - If both auto_repeat_mode and key are specified, then the - auto_repeat_mode of that key is changed, if possible. If only - auto_repeat_mode is specified, then the global auto-repeat mode - for the entire keyboard is changed, if possible, without - affecting the per-key settings. It is a Match error if a key is - specified without an auto_repeat_mode. - - The order in which controls are verified and altered is - server-dependent. If an error is generated, a subset of the - controls may have been altered. - - Those feedback controls equivalent to those of the core pointer - are controlled by feedback class PtrFeedbackClass using the - PtrFeedbackControl structure. The members of that structure are - as follows: - - PTRFEEDBACKCTL: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - accelNumerator: INT16 - accelDenominator: INT16 - threshold: INT16] - - The acceleration, expressed as a fraction, is a multiplier for - movement. For example, specifying 3/1 means the device moves - three times as fast as normal. The fraction may be rounded - arbitrarily by the X server. Acceleration only takes effect if - the device moves more than threshold pixels at once and only - applies to the amount beyond the value in the threshold - argument. Setting a value to -1 restores the default. The - values of the do-accel and do-threshold arguments must be - nonzero for the device values to be set. Otherwise, the - parameters will be unchanged. Negative values generate a Value - error, as does a zero value for the accel-denominator argument. - - Some devices are capable of displaying an integer. This is done - using feedback class IntegerFeedbackClass using the - IntegerFeedbackControl structure. The members of that structure - are as follows: - - INTEGERCTL: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - int_to_display: INT32] - - Some devices are capable of displaying a string. This is done - using feedback class StringFeedbackClass using the - StringFeedbackCtl structure. The members of that structure are - as follows: - - STRINGCTL: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - syms_to_display: LISTofKEYSYMS] - - Some devices contain a bell. This is done using feedback class - BellFeedbackClass using the BellFeedbackControl structure. The - members of that structure are as follows: - - BELLCTL: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - percent: INT8 - pitch: INT16 - duration: INT16] - - Some devices contain leds. These can be turned on and off using - the LedFeedbackControl structure. The members of that structure - are as follows: - - LEDCTL: - [class: CARD8 - length: CARD16 - feedback id: CARD8 - led_mask: BITMASK - led_value: BITMASK] +Feedback controls are grouped by class. Those feedbacks that +are equivalent to those supported by the core keyboard are +controlled by feedback class KbdFeedbackClass using the +KbdFeedbackControl structure. The members of that structure +are: + + KBDFEEDBACKCTL + [class: CARD8 + length: CARD16 + feedback id: CARD8 + key_click_percent: INT8 + bell_percent: INT8 + bell_pitch: INT16 + bell_duration: INT16 + led_mask: INT32 + led_value: INT32 + key: KEYCODE + auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff, + AutoRepeatModeDefault}] + +The key_click_percent sets the volume for key clicks between 0 +(off) and 100 (loud) inclusive, if possible. Setting to -1 +restores the default. Other negative values generate a Value +error. + +If both auto_repeat_mode and key are specified, then the +auto_repeat_mode of that key is changed, if possible. If only +auto_repeat_mode is specified, then the global auto-repeat mode +for the entire keyboard is changed, if possible, without +affecting the per-key settings. It is a Match error if a key is +specified without an auto_repeat_mode. + +The order in which controls are verified and altered is +server-dependent. If an error is generated, a subset of the +controls may have been altered. + +Those feedback controls equivalent to those of the core pointer +are controlled by feedback class PtrFeedbackClass using the +PtrFeedbackControl structure. The members of that structure are +as follows: + + PTRFEEDBACKCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + accelNumerator: INT16 + accelDenominator: INT16 + threshold: INT16] + +The acceleration, expressed as a fraction, is a multiplier for +movement. For example, specifying 3/1 means the device moves +three times as fast as normal. The fraction may be rounded +arbitrarily by the X server. Acceleration only takes effect if +the device moves more than threshold pixels at once and only +applies to the amount beyond the value in the threshold +argument. Setting a value to -1 restores the default. The +values of the do-accel and do-threshold arguments must be +nonzero for the device values to be set. Otherwise, the +parameters will be unchanged. Negative values generate a Value +error, as does a zero value for the accel-denominator argument. + +Some devices are capable of displaying an integer. This is done +using feedback class IntegerFeedbackClass using the +IntegerFeedbackControl structure. The members of that structure +are as follows: + + INTEGERCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + int_to_display: INT32] + +Some devices are capable of displaying a string. This is done +using feedback class StringFeedbackClass using the +StringFeedbackCtl structure. The members of that structure are +as follows: + + STRINGCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + syms_to_display: LISTofKEYSYMS] + +Some devices contain a bell. This is done using feedback class +BellFeedbackClass using the BellFeedbackControl structure. The +members of that structure are as follows: + + BELLCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + percent: INT8 + pitch: INT16 + duration: INT16] + +Some devices contain leds. These can be turned on and off using +the LedFeedbackControl structure. The members of that structure +are as follows: + + LEDCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + led_mask: BITMASK + led_value: BITMASK] Errors: Device, Match, Value 2.20 Ringing a Bell on an Input Device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To ring a bell on an extension input device, use DeviceBell. +To ring a bell on an extension input device, use DeviceBell. - DeviceBell: - device: DEVICE - feedbackclass: CARD8 - feedbackid: CARD8 - percent: INT8 + DeviceBell: + device: DEVICE + feedbackclass: CARD8 + feedbackid: CARD8 + percent: INT8 Errors: Device, Value - This request is analogous to the core Bell request. It rings - the specified bell on the specified input device feedback, - using the specified volume. The specified volume is relative to - the base volume for the feedback. If the value for the percent - argument is not in the range -100 to 100 inclusive, a Value - error results. The volume at which the bell rings when the - percent argument is nonnegative is: +This request is analogous to the core Bell request. It rings +the specified bell on the specified input device feedback, +using the specified volume. The specified volume is relative to +the base volume for the feedback. If the value for the percent +argument is not in the range -100 to 100 inclusive, a Value +error results. The volume at which the bell rings when the +percent argument is nonnegative is: - base - [(base * percent) / 100] + percent + base - [(base * percent) / 100] + percent - The volume at which the bell rings when the percent argument is - negative is: +The volume at which the bell rings when the percent argument is +negative is: - base + [(base * percent) / 100] + base + [(base * percent) / 100] - To change the base volume of the bell, use - ChangeFeedbackControl request. +To change the base volume of the bell, use +ChangeFeedbackControl request. Controlling Device Encoding - To get the keyboard mapping of an extension device that has - keys, use GetDeviceKeyMapping. +To get the keyboard mapping of an extension device that has +keys, use GetDeviceKeyMapping. - GetDeviceKeyMapping - device: DEVICE - first-keycode: KEYCODE - count: CARD8 - => - keysyms-per-keycode: CARD8 - keysyms: LISTofKEYSYM + GetDeviceKeyMapping + device: DEVICE + first-keycode: KEYCODE + count: CARD8 + => + keysyms-per-keycode: CARD8 + keysyms: LISTofKEYSYM Errors: Device, Match, Value - This request returns the symbols for the specified number of - keycodes for the specified extension device, starting with the - specified keycode. The first-keycode must be greater than or - equal to min-keycode as returned in the connection setup (else - a Value error), and +This request returns the symbols for the specified number of +keycodes for the specified extension device, starting with the +specified keycode. The first-keycode must be greater than or +equal to min-keycode as returned in the connection setup (else +a Value error), and - first-keycode + count - 1 + first-keycode + count - 1 - must be less than or equal to max-keycode as returned in the - connection setup (else a Value error). The number of elements - in the keysyms list is +must be less than or equal to max-keycode as returned in the +connection setup (else a Value error). The number of elements +in the keysyms list is - count * keysyms-per-keycode + count * keysyms-per-keycode - and KEYSYM number N (counting from zero) for keycode K has an - index (counting from zero) of +and KEYSYM number N (counting from zero) for keycode K has an +index (counting from zero) of - (K - first-keycode) * keysyms-per-keycode + N + (K - first-keycode) * keysyms-per-keycode + N - in keysyms. The keysyms-per-keycode value is chosen arbitrarily - by the server to be large enough to report all requested - symbols. A special KEYSYM value of NoSymbol is used to fill in - unused elements for individual keycodes. +in keysyms. The keysyms-per-keycode value is chosen arbitrarily +by the server to be large enough to report all requested +symbols. A special KEYSYM value of NoSymbol is used to fill in +unused elements for individual keycodes. - If the specified device has not first been opened by this - client via OpenDevice, or if that device does not support input - class Keys, this request will fail with a Device error. +If the specified device has not first been opened by this +client via OpenDevice, or if that device does not support input +class Keys, this request will fail with a Device error. - To change the keyboard mapping of an extension device that has - keys, use ChangeDeviceKeyMapping. +To change the keyboard mapping of an extension device that has +keys, use ChangeDeviceKeyMapping. - ChangeDeviceKeyMapping - device: DEVICE - first-keycode: KEYCODE - keysyms-per-keycode: CARD8 - keysyms: LISTofKEYSYM - num_codes: CARD8 + ChangeDeviceKeyMapping + device: DEVICE + first-keycode: KEYCODE + keysyms-per-keycode: CARD8 + keysyms: LISTofKEYSYM + num_codes: CARD8 Errors: Device, Match, Value, Alloc - This request is analogous to the core ChangeKeyMapping request. - It defines the symbols for the specified number of keycodes for - the specified extension device. If the specified device has not - first been opened by this client via OpenDevice, or if that - device does not support input class Keys, this request will - fail with a Device error. - - The number of elements in the keysyms list must be a multiple - of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping - generates a Length error. The specified first_keycode must be - greater than or equal to the min_keycode value returned by the - ListInputDevices request, or this request will fail with a - Value error. In addition, if the following expression is not - less than the max_keycode value returned by the - ListInputDevices request, the request will fail with a Value - error: - - first_keycode + (num_codes / keysyms_per_keycode) - 1 - - To obtain the keycodes that are used as modifiers on an - extension device that has keys, use GetDeviceModifierMapping. - - GetDeviceModifierMapping - device: DEVICE - => - keycodes-per-modifier: CARD8 - keycodes: LISTofKEYCODE +This request is analogous to the core ChangeKeyMapping request. +It defines the symbols for the specified number of keycodes for +the specified extension device. If the specified device has not +first been opened by this client via OpenDevice, or if that +device does not support input class Keys, this request will +fail with a Device error. + +The number of elements in the keysyms list must be a multiple +of keysyms_per_keycode. Otherwise, ChangeDeviceKeyMapping +generates a Length error. The specified first_keycode must be +greater than or equal to the min_keycode value returned by the +ListInputDevices request, or this request will fail with a +Value error. In addition, if the following expression is not +less than the max_keycode value returned by the +ListInputDevices request, the request will fail with a Value +error: + + first_keycode + (num_codes / keysyms_per_keycode) - 1 + +To obtain the keycodes that are used as modifiers on an +extension device that has keys, use GetDeviceModifierMapping. + + GetDeviceModifierMapping + device: DEVICE + => + keycodes-per-modifier: CARD8 + keycodes: LISTofKEYCODE Errors: Device, Match - This request is analogous to the core GetModifierMapping - request. This request returns the keycodes of the keys being - used as modifiers. The number of keycodes in the list is - 8*keycodes-per-modifier. The keycodes are divided into eight - sets, with each set containing keycodes-per-modifier elements. - The sets are assigned in order to the modifiers Shift, Lock, - Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The - keycodes-per-modifier value is chosen arbitrarily by the - server; zeroes are used to fill in unused elements within each - set. If only zero values are given in a set, the use of the - corresponding modifier has been disabled. The order of keycodes - within each set is chosen arbitrarily by the server. - - To set which keycodes that are to be used as modifiers for an - extension device, use SetDeviceModifierMapping. - - SetDeviceModifierMapping - device: DEVICE - keycodes-per-modifier: CARD8 - keycodes: LISTofKEYCODE - => - status: {Success, Busy, Failed} +This request is analogous to the core GetModifierMapping +request. This request returns the keycodes of the keys being +used as modifiers. The number of keycodes in the list is +8*keycodes-per-modifier. The keycodes are divided into eight +sets, with each set containing keycodes-per-modifier elements. +The sets are assigned in order to the modifiers Shift, Lock, +Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The +keycodes-per-modifier value is chosen arbitrarily by the +server; zeroes are used to fill in unused elements within each +set. If only zero values are given in a set, the use of the +corresponding modifier has been disabled. The order of keycodes +within each set is chosen arbitrarily by the server. + +To set which keycodes that are to be used as modifiers for an +extension device, use SetDeviceModifierMapping. + + SetDeviceModifierMapping + device: DEVICE + keycodes-per-modifier: CARD8 + keycodes: LISTofKEYCODE + => + status: {Success, Busy, Failed} Errors: Device, Match, Value, Alloc - This request is analogous to the core SetModifierMapping - request. This request specifies the keycodes (if any) of the - keys to be used as modifiers. The number of keycodes in the - list must be 8*keycodes-per-modifier (else a Length error). The - keycodes are divided into eight sets, with the sets, with each - set containing keycodes-per-modifier elements. The sets are - assigned in order to the modifiers Shift, Lock, Control, Mod1, - Mod2, Mod3, Mod4, and Mod5. Only non-zero keycode values are - used within each set; zero values are ignored. All of the - non-zero keycodes must be in the range specified by min-keycode - and max-keycode in the ListInputDevices request (else a Value - error). The order of keycodes within a set does not matter. If - no non-zero values are specified in a set, the use of the - corresponding modifier is disabled, and the modifier bit will - always be zero. Otherwise, the modifier bit will be one - whenever at least one of the keys in the corresponding set is - in the down position. - - A server can impose restrictions on how modifiers can be - changed (for example, if certain keys do not generate up - transitions in hardware or if multiple keys per modifier are - not supported). If some such restriction is violated, the status - reply is MappingFailed, and none of the modifiers are changed. - - If the new keycodes specified for a modifier differ from those - currently defined and any (current or new) keys for that - modifier are in the logically down state, the status reply is - MappingBusy, and none of the modifiers are changed. - - This request generates a DeviceMappingNotify event on a Success - status. The DeviceMappingNotify event will be sent only to - those clients that have expressed an interest in receiving that - event via the XSelectExtensionEvent request. +This request is analogous to the core SetModifierMapping +request. This request specifies the keycodes (if any) of the +keys to be used as modifiers. The number of keycodes in the +list must be 8*keycodes-per-modifier (else a Length error). The +keycodes are divided into eight sets, with the sets, with each +set containing keycodes-per-modifier elements. The sets are +assigned in order to the modifiers Shift, Lock, Control, Mod1, +Mod2, Mod3, Mod4, and Mod5. Only non-zero keycode values are +used within each set; zero values are ignored. All of the +non-zero keycodes must be in the range specified by min-keycode +and max-keycode in the ListInputDevices request (else a Value +error). The order of keycodes within a set does not matter. If +no non-zero values are specified in a set, the use of the +corresponding modifier is disabled, and the modifier bit will +always be zero. Otherwise, the modifier bit will be one +whenever at least one of the keys in the corresponding set is +in the down position. + +A server can impose restrictions on how modifiers can be +changed (for example, if certain keys do not generate up +transitions in hardware or if multiple keys per modifier are +not supported). If some such restriction is violated, the status +reply is MappingFailed, and none of the modifiers are changed. + +If the new keycodes specified for a modifier differ from those +currently defined and any (current or new) keys for that +modifier are in the logically down state, the status reply is +MappingBusy, and none of the modifiers are changed. + +This request generates a DeviceMappingNotify event on a Success +status. The DeviceMappingNotify event will be sent only to +those clients that have expressed an interest in receiving that +event via the XSelectExtensionEvent request. 2.20 Controlling Button Mapping +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - These requests are analogous to the core GetPointerMapping and - ChangePointerMapping requests. They allow a client to determine - the current mapping of buttons on an extension device, and to - change that mapping. +These requests are analogous to the core GetPointerMapping and +ChangePointerMapping requests. They allow a client to determine +the current mapping of buttons on an extension device, and to +change that mapping. - To get the current button mapping for an extension device, use - GetDeviceButtonMapping. +To get the current button mapping for an extension device, use +GetDeviceButtonMapping. - GetDeviceButtonMapping - device: DEVICE - nmap: CARD8 - => - map_return: LISTofCARD8 + GetDeviceButtonMapping + device: DEVICE + nmap: CARD8 + => + map_return: LISTofCARD8 Errors: Device, Match - The GetDeviceButtonMapping function returns the current mapping - of the buttons on the specified device. Elements of the list - are indexed starting from one. The length of the list indicates - the number of physical buttons. The nominal mapping is the - identity mapping map[i]=i. +The GetDeviceButtonMapping function returns the current mapping +of the buttons on the specified device. Elements of the list +are indexed starting from one. The length of the list indicates +the number of physical buttons. The nominal mapping is the +identity mapping map[i]=i. - nmap indicates the number of elements in the map_return array. - Only the first nmap entries will be copied by the library into - the map_return array. +nmap indicates the number of elements in the map_return array. +Only the first nmap entries will be copied by the library into +the map_return array. - To set the button mapping for an extension device, use - SetDeviceButtonMapping. +To set the button mapping for an extension device, use +SetDeviceButtonMapping. - SetDeviceButtonMapping - device: DEVICE - map: LISTofCARD8 - nmap: CARD8 - => - status: CARD8 + SetDeviceButtonMapping + device: DEVICE + map: LISTofCARD8 + nmap: CARD8 + => + status: CARD8 Errors: Device, Match, Value - The SetDeviceButtonMapping function sets the mapping of the - specified device and causes the X server to generate a - DeviceMappingNotify event on a status of MappingSuccess. - Elements of the list are indexed starting from one. The length - of the list, specified in nmap, must be the same as - GetDeviceButtonMapping would return. Otherwise, - SetDeviceButtonMapping generates a Value error. A zero element - disables a button, and elements are not restricted in value by - the number of physical buttons. If any of the buttons to be - altered are in the down state, the status reply is MappingBusy - and the mapping is not changed. - - In servers supporting XI 1.x, no two elements can have the same - nonzero value. Otherwise, this function generates a Value - error. +The SetDeviceButtonMapping function sets the mapping of the +specified device and causes the X server to generate a +DeviceMappingNotify event on a status of MappingSuccess. +Elements of the list are indexed starting from one. The length +of the list, specified in nmap, must be the same as +GetDeviceButtonMapping would return. Otherwise, +SetDeviceButtonMapping generates a Value error. A zero element +disables a button, and elements are not restricted in value by +the number of physical buttons. If any of the buttons to be +altered are in the down state, the status reply is MappingBusy +and the mapping is not changed. + +In servers supporting XI 1.x, no two elements can have the same +nonzero value. Otherwise, this function generates a Value +error. 2.21 Obtaining The State Of A Device +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To obtain vectors that describe the state of the keys, buttons +and valuators of an extension device, use QueryDeviceState. - To obtain vectors that describe the state of the keys, buttons - and valuators of an extension device, use QueryDeviceState. - - QueryDeviceState - device: DEVICE - => - device-id: CARD8 - data: LISTofINPUTCLASS - - where - - INPUTCLASS: {VALUATOR, BUTTON, KEY} - CLASS VALUATOR: - [class: CARD8 - num_valuators: CARD8 - mode: CARD8 - #x01 device mode (0 = Relative, 1 = Absolute) - #x02 proximity state (0 = InProximity, 1 = OutOfProximity) - valuators: LISTofINT32] - CLASS BUTTON: - [class: CARD8 - num_buttons: CARD8 - buttons: LISTofCARD8] - CLASS KEY: - [class: CARD8 - num_keys: CARD8 - keys: LISTofCARD8] + QueryDeviceState + device: DEVICE + => + device-id: CARD8 + data: LISTofINPUTCLASS + +where + + INPUTCLASS: {VALUATOR, BUTTON, KEY} + CLASS VALUATOR: + [class: CARD8 + num_valuators: CARD8 + mode: CARD8 + #x01 device mode (0 = Relative, 1 = Absolute) + #x02 proximity state (0 = InProximity, 1 = OutOfProximity) + valuators: LISTofINT32] + CLASS BUTTON: + [class: CARD8 + num_buttons: CARD8 + buttons: LISTofCARD8] + CLASS KEY: + [class: CARD8 + num_keys: CARD8 + keys: LISTofCARD8] Errors: Device - The QueryDeviceState request returns the current logical state - of the buttons, keys, and valuators on the specified input - device. The buttons and keys arrays, byte N (from 0) contains - the bits for key or button 8N to 8N+7 with the least - significant bit in the byte representing key or button 8N. +The QueryDeviceState request returns the current logical state +of the buttons, keys, and valuators on the specified input +device. The buttons and keys arrays, byte N (from 0) contains +the bits for key or button 8N to 8N+7 with the least +significant bit in the byte representing key or button 8N. - If the device has valuators, a bit in the mode field indicates - whether the device is reporting Absolute or Relative data. If - it is reporting Absolute data, the valuators array will contain - the current value of the valuators. If it is reporting Relative - data, the valuators array will contain undefined data. +If the device has valuators, a bit in the mode field indicates +whether the device is reporting Absolute or Relative data. If +it is reporting Absolute data, the valuators array will contain +the current value of the valuators. If it is reporting Relative +data, the valuators array will contain undefined data. - If the device reports proximity information, a bit in the mode - field indicates whether the device is InProximity or - OutOfProximity. +If the device reports proximity information, a bit in the mode +field indicates whether the device is InProximity or +OutOfProximity. 2.22 Listing Device Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Introduced with XI 1.5 +Introduced with XI 1.5 - ListDeviceProperties - deviceid: CARD8 - => - nAtoms: CARD16 - Atoms: LISTofATOM + ListDeviceProperties + deviceid: CARD8 + => + nAtoms: CARD16 + Atoms: LISTofATOM Errors: Device - Each device can store an arbitrary number of properties. These - properties can be allocated by either the client or the driver. - The client can change device properties and the server - guarantees that the device driver is notified about a change of - the device's properties. +Each device can store an arbitrary number of properties. These +properties can be allocated by either the client or the driver. +The client can change device properties and the server +guarantees that the device driver is notified about a change of +the device's properties. - ListDeviceProperties returns all properties of a device. The - client is expected to retrieve details about the properties it - is interested in separately. +ListDeviceProperties returns all properties of a device. The +client is expected to retrieve details about the properties it +is interested in separately. 2.23 Getting a Device Property - - Introduced with XI 1.5 - - GetDeviceProperty: - property: ATOM - type: ATOM - longOffset: CARD32 - longLength: CARD32 - deviceid: CARD8 - delete: BOOL - => - propertyType: ATOM - bytesAfter: CARD32 - nItems: CARD32 - format: CARD8 - deviceid: CARD8 - data: [LISTofCARD8] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Introduced with XI 1.5 + + GetDeviceProperty: + property: ATOM + type: ATOM + longOffset: CARD32 + longLength: CARD32 + deviceid: CARD8 + delete: BOOL + => + propertyType: ATOM + bytesAfter: CARD32 + nItems: CARD32 + format: CARD8 + deviceid: CARD8 + data: [LISTofCARD8] Errors: Atom, Device, Value, Access - Retrieve the value for a property. If the property does not - exist, propertyType is None and all other fields are undefined. +Retrieve the value for a property. If the property does not +exist, propertyType is None and all other fields are undefined. - If type is not AnyPropertyType and does not match the - property's actual type, the propertyType, bytesAfter, and - format are returned but not the actual data. +If type is not AnyPropertyType and does not match the +property's actual type, the propertyType, bytesAfter, and +format are returned but not the actual data. - longOffset and longLength specify the offset and length - respectively in 32-bit multiples of the data to retrieve. +longOffset and longLength specify the offset and length +respectively in 32-bit multiples of the data to retrieve. - If delete is True, the property is deleted after querying its - data. If the property cannot be deleted, a BadAccess error is - returned. +If delete is True, the property is deleted after querying its +data. If the property cannot be deleted, a BadAccess error is +returned. - propertyType returns the atom identifier that defines the - actual type of the property. +propertyType returns the atom identifier that defines the +actual type of the property. - If bytesAfter is non-zero, it specifies the number of data - 4-byte units after the retrieved chunk of data. +If bytesAfter is non-zero, it specifies the number of data +4-byte units after the retrieved chunk of data. - format specifies whether the data should be viewed as a list of - 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, - and 32. This information allows the X server to correctly - perform byte-swap operations as necessary. +format specifies whether the data should be viewed as a list of +8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, +and 32. This information allows the X server to correctly +perform byte-swap operations as necessary. - nItem specifies the number of 8-bit, 16-bit, or 32-bit items - returned after the request. +nItem specifies the number of 8-bit, 16-bit, or 32-bit items +returned after the request. 2.24 Changing a Device Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Introduced with XI 1.5 +Introduced with XI 1.5 - ChangeDeviceProperty: - property: ATOM - type: ATOM - deviceid: CARD8 - format: CARD8 - mode: CARD8 - nUnits: CARD32 + ChangeDeviceProperty: + property: ATOM + type: ATOM + deviceid: CARD8 + format: CARD8 + mode: CARD8 + nUnits: CARD32 Errors: Atom, Device, Value, Match, Access - Changes the value of a specified property. +Changes the value of a specified property. - The type specifies the atom identifier that defines the type of - the property. If mode is not PropModeReplace, the type must - match the current type of the property or a BadMatch error is - returned. +The type specifies the atom identifier that defines the type of +the property. If mode is not PropModeReplace, the type must +match the current type of the property or a BadMatch error is +returned. - format specifies whether the data should be viewed as a list of - 8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, - and 32. This information allows the X server to correctly - perform byte-swap operations as necessary. +format specifies whether the data should be viewed as a list of +8-bit, 16-bit, or 32-bit quantities. Possible values are 8, 16, +and 32. This information allows the X server to correctly +perform byte-swap operations as necessary. - If mode is PropModeReplace, a preexising value for this - property is replaced with the new value. If mode is - PropModePrepend or PropModeAppend, the value is prepended or - appended, respectively, to the current value of the property. +If mode is PropModeReplace, a preexising value for this +property is replaced with the new value. If mode is +PropModePrepend or PropModeAppend, the value is prepended or +appended, respectively, to the current value of the property. - nUnits specifies the number of 8-bit, 16-bit, or 32-bit items - supplied after the reply. +nUnits specifies the number of 8-bit, 16-bit, or 32-bit items +supplied after the reply. - Changing a device property results in a - DevicePropertyNotifyEvent being sent to all clients. +Changing a device property results in a +DevicePropertyNotifyEvent being sent to all clients. 2.25 Deleting a Device Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Introduced with XI 1.5 +Introduced with XI 1.5 - DeleteDeviceProperty: - property: ATOM - deviceid: CARD8 + DeleteDeviceProperty: + property: ATOM + deviceid: CARD8 Errors: Atom, Device, Match, Access. - Deletes the specified property. If the property cannot be - deleted by the client, a BadAccess error is returned. +Deletes the specified property. If the property cannot be +deleted by the client, a BadAccess error is returned. 3. Events +--------- - The input extension creates input events analogous to the core - input events. These extension input events are generated by - manipulating one of the extension input devices. +The input extension creates input events analogous to the core +input events. These extension input events are generated by +manipulating one of the extension input devices. 3.1 Button, Key, and Motion Events - - DeviceKeyPress - DeviceKeyRelease - DeviceButtonPress, - DeviceButtonRelease - DeviceMotionNotify - device: CARD8 - root, event: WINDOW - child: Window or None - same-screen: BOOL - root-x, root-y, event-x, event-y: INT16 - detail: <see below> - state: SETofKEYBUTMASK - time: TIMESTAMP - - These events are generated when a key, button, or valuator - logically changes state. The generation of these logical - changes may lag the physical changes, if device event - processing is frozen. Note that DeviceKeyPress and - DeviceKeyRelease are generated for all keys, even those mapped - to modifier bits. The “source” of the event is the window the - pointer is in. The window with respect to which the event is - normally reported is found by looking up the hierarchy - (starting with the source window) for the first window on which - any client has selected interest in the event. The actual - window used for reporting can be modified by active grabs and - by the focus window.The window the event is reported with - respect to is called the “event” window. - - The root is the root window of the “source” window, and root-x - and root-y are the pointer coordinates relative to root's - origin at the time of the event. Event is the “event” window. - If the event window is on the same screen as root, then event-x - and event-y are the pointer coordinates relative to the event - window's origin. Otherwise, event-x and event-y are zero. If - the source window is an inferior of the event window, then - child is set to the child of the event window that is an - ancestor of (or is) the source window. Otherwise, it is set to - None. - - The state component gives the logical state of the buttons on - the X pointer and modifier keys on the core X keyboard just - before the event. - - The detail component type varies with the event type: - Event Component - DeviceKeyPress KEYCODE - DeviceKeyRelease KEYCODE - DeviceButtonPress BUTTON - DeviceButtonRelease BUTTON - DeviceMotionNotify { Normal , Hint } - - The granularity of motion events is not guaranteed, but a - client selecting for motion events is guaranteed to get at - least one event when a valuator changes. If DeviceMotionHint is - selected, the server is free to send only one - DeviceMotionNotify event (with detail Hint) to the client for - the event window, until either a key or button changes state, - the pointer leaves the event window, or the client issues a - QueryDeviceState or GetDeviceMotionEvents request. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + DeviceKeyPress + DeviceKeyRelease + DeviceButtonPress, + DeviceButtonRelease + DeviceMotionNotify + device: CARD8 + root, event: WINDOW + child: Window or None + same-screen: BOOL + root-x, root-y, event-x, event-y: INT16 + detail: <see below> + state: SETofKEYBUTMASK + time: TIMESTAMP + +These events are generated when a key, button, or valuator +logically changes state. The generation of these logical +changes may lag the physical changes, if device event +processing is frozen. Note that DeviceKeyPress and +DeviceKeyRelease are generated for all keys, even those mapped +to modifier bits. The “source” of the event is the window the +pointer is in. The window with respect to which the event is +normally reported is found by looking up the hierarchy +(starting with the source window) for the first window on which +any client has selected interest in the event. The actual +window used for reporting can be modified by active grabs and +by the focus window.The window the event is reported with +respect to is called the “event” window. + +The root is the root window of the “source” window, and root-x +and root-y are the pointer coordinates relative to root's +origin at the time of the event. Event is the “event” window. +If the event window is on the same screen as root, then event-x +and event-y are the pointer coordinates relative to the event +window's origin. Otherwise, event-x and event-y are zero. If +the source window is an inferior of the event window, then +child is set to the child of the event window that is an +ancestor of (or is) the source window. Otherwise, it is set to +None. + +The state component gives the logical state of the buttons on +the X pointer and modifier keys on the core X keyboard just +before the event. + +The detail component type varies with the event type: +Event Component +DeviceKeyPress KEYCODE +DeviceKeyRelease KEYCODE +DeviceButtonPress BUTTON +DeviceButtonRelease BUTTON +DeviceMotionNotify { Normal , Hint } + +The granularity of motion events is not guaranteed, but a +client selecting for motion events is guaranteed to get at +least one event when a valuator changes. If DeviceMotionHint is +selected, the server is free to send only one +DeviceMotionNotify event (with detail Hint) to the client for +the event window, until either a key or button changes state, +the pointer leaves the event window, or the client issues a +QueryDeviceState or GetDeviceMotionEvents request. 3.2 DeviceValuator Event - - DeviceValuator - device: CARD8 - device_state: SETofKEYBUTMASK - num_valuators: CARD8 - first_valuator: CARD8 - valuators: LISTofINT32 - - DeviceValuator events are generated to contain valuator - information for which there is insufficient space in DeviceKey, - DeviceButton, DeviceMotion, and Proximity wire events. For - events of these types, a second event of type DeviceValuator - follows immediately. The library combines these events into a - single event that a client can receive via XNextEvent. - DeviceValuator events are not selected for by clients, they - only exist to contain information that will not fit into some - event selected by clients. - - The device_state component gives the state of the buttons and - modifiers on the device generating the event. - - Extension motion devices may report motion data for a variable - number of axes. The valuators array contains the values of all - axes reported by the device. If more than 6 axes are reported, - more than one DeviceValuator event will be sent by the server, - and more than one DeviceKey, DeviceButton, DeviceMotion, or - Proximity event will be reported by the library. Clients should - examine the corresponding fields of the event reported by the - library to determine the total number of axes reported, and the - first axis reported in the current event. Axes are numbered - beginning with zero. - - For Button, Key and Motion events on a device reporting - absolute motion data the current value of the device's - valuators is reported. For devices that report relative data, - Button and Key events may be followed by a DeviceValuator event - that contains 0s in the num_valuators field. In this case, only - the device_state component will have meaning. +~~~~~~~~~~~~~~~~~~~~~~~~ + + DeviceValuator + device: CARD8 + device_state: SETofKEYBUTMASK + num_valuators: CARD8 + first_valuator: CARD8 + valuators: LISTofINT32 + +DeviceValuator events are generated to contain valuator +information for which there is insufficient space in DeviceKey, +DeviceButton, DeviceMotion, and Proximity wire events. For +events of these types, a second event of type DeviceValuator +follows immediately. The library combines these events into a +single event that a client can receive via XNextEvent. +DeviceValuator events are not selected for by clients, they +only exist to contain information that will not fit into some +event selected by clients. + +The device_state component gives the state of the buttons and +modifiers on the device generating the event. + +Extension motion devices may report motion data for a variable +number of axes. The valuators array contains the values of all +axes reported by the device. If more than 6 axes are reported, +more than one DeviceValuator event will be sent by the server, +and more than one DeviceKey, DeviceButton, DeviceMotion, or +Proximity event will be reported by the library. Clients should +examine the corresponding fields of the event reported by the +library to determine the total number of axes reported, and the +first axis reported in the current event. Axes are numbered +beginning with zero. + +For Button, Key and Motion events on a device reporting +absolute motion data the current value of the device's +valuators is reported. For devices that report relative data, +Button and Key events may be followed by a DeviceValuator event +that contains 0s in the num_valuators field. In this case, only +the device_state component will have meaning. 3.3 Device Focus Events - - DeviceFocusIn - DeviceFocusOut - device: CARD8 - time: TIMESTAMP - event: WINDOW - mode: { Normal, WhileGrabbed, Grab, Ungrab} - detail: { Ancestor, Virtual, Inferior, Nonlinear, - NonlinearVirtual, Pointer, PointerRoot, None} - - These events are generated when the input focus changes and are - reported to clients selecting DeviceFocusChange for the - specified device and window. Events generated by SetDeviceFocus - when the device is not grabbed have mode Normal. Events - generated by SetDeviceFocus when the device is grabbed have - mode WhileGrabbed. Events generated when a device grab activates - have mode Grab, and events generated when a device grab - deactivates have mode Ungrab. - - All DeviceFocusOut events caused by a window unmap are - generated after any UnmapNotify event, but the ordering of - DeviceFocusOut with respect to generated EnterNotify, - LeaveNotify, VisibilityNotify and Expose events is not - constrained. - - DeviceFocusIn and DeviceFocusOut events are generated for focus - changes of extension devices in the same manner as focus events - for the core devices are generated. +~~~~~~~~~~~~~~~~~~~~~~~ + + DeviceFocusIn + DeviceFocusOut + device: CARD8 + time: TIMESTAMP + event: WINDOW + mode: { Normal, WhileGrabbed, Grab, Ungrab} + detail: { Ancestor, Virtual, Inferior, Nonlinear, + NonlinearVirtual, Pointer, PointerRoot, None} + +These events are generated when the input focus changes and are +reported to clients selecting DeviceFocusChange for the +specified device and window. Events generated by SetDeviceFocus +when the device is not grabbed have mode Normal. Events +generated by SetDeviceFocus when the device is grabbed have +mode WhileGrabbed. Events generated when a device grab activates +have mode Grab, and events generated when a device grab +deactivates have mode Ungrab. + +All DeviceFocusOut events caused by a window unmap are +generated after any UnmapNotify event, but the ordering of +DeviceFocusOut with respect to generated EnterNotify, +LeaveNotify, VisibilityNotify and Expose events is not +constrained. + +DeviceFocusIn and DeviceFocusOut events are generated for focus +changes of extension devices in the same manner as focus events +for the core devices are generated. 3.4 Device State Notify Event - - DeviceStateNotify - time: TIMESTAMP - device: CARD8 - num_keys: CARD8 - num_buttons: CARD8 - num_valuators: CARD8 - classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass} - SetOfDeviceMode: - #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity - #x40 Device Mode (0 = Relative, 1 = Absolute) - SetOfInputClass: #x04 reporting valuators - #x02 reporting buttons - #x01 reporting keys - buttons: LISTofCARD8 - keys: LISTofCARD8 - valuators: LISTofCARD32 - - This event reports the state of the device just as in the - QueryDeviceState request. This event is reported to clients - selecting DeviceStateNotify for the device and window and is - generated immediately after every EnterNotify and - DeviceFocusIn. If the device has no more than 32 buttons, no - more than 32 keys, and no more than 3 valuators, This event can - report the state of the device. If the device has more than 32 - buttons, the event will be immediately followed by a - DeviceButtonStateNotify event. If the device has more than 32 - keys, the event will be followed by a DeviceKeyStateNotify - event. If the device has more than 3 valuators, the event will - be followed by one or more DeviceValuator events. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + DeviceStateNotify + time: TIMESTAMP + device: CARD8 + num_keys: CARD8 + num_buttons: CARD8 + num_valuators: CARD8 + classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass} + SetOfDeviceMode: + #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity + #x40 Device Mode (0 = Relative, 1 = Absolute) + SetOfInputClass: #x04 reporting valuators + #x02 reporting buttons + #x01 reporting keys + buttons: LISTofCARD8 + keys: LISTofCARD8 + valuators: LISTofCARD32 + +This event reports the state of the device just as in the +QueryDeviceState request. This event is reported to clients +selecting DeviceStateNotify for the device and window and is +generated immediately after every EnterNotify and +DeviceFocusIn. If the device has no more than 32 buttons, no +more than 32 keys, and no more than 3 valuators, This event can +report the state of the device. If the device has more than 32 +buttons, the event will be immediately followed by a +DeviceButtonStateNotify event. If the device has more than 32 +keys, the event will be followed by a DeviceKeyStateNotify +event. If the device has more than 3 valuators, the event will +be followed by one or more DeviceValuator events. 3.5 Device KeyState and ButtonState Notify Events - - DeviceKeyStateNotify - device: CARD8 - keys: LISTofCARD8 - DeviceButtonStateNotify - device: CARD8 - buttons: LISTofCARD8 - - These events contain information about the state of keys and - buttons on a device that will not fit into the - DeviceStateNotify wire event. These events are not selected by - clients, rather they may immediately follow a DeviceStateNotify - wire event and be combined with it into a single - DeviceStateNotify client event that a client may receive via - XNextEvent. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + DeviceKeyStateNotify + device: CARD8 + keys: LISTofCARD8 + DeviceButtonStateNotify + device: CARD8 + buttons: LISTofCARD8 + +These events contain information about the state of keys and +buttons on a device that will not fit into the +DeviceStateNotify wire event. These events are not selected by +clients, rather they may immediately follow a DeviceStateNotify +wire event and be combined with it into a single +DeviceStateNotify client event that a client may receive via +XNextEvent. 3.6 DeviceMappingNotify Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - DeviceMappingNotify - time: TIMESTAMP - device: CARD8 - request: CARD8 - first_keycode: CARD8 - count: CARD8 + DeviceMappingNotify + time: TIMESTAMP + device: CARD8 + request: CARD8 + first_keycode: CARD8 + count: CARD8 - This event reports a change in the mapping of keys, modifiers, - or buttons on an extension device. This event is reported to - clients selecting DeviceMappingNotify for the device and window - and is generated after every client SetDeviceButtonMapping, - ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request. +This event reports a change in the mapping of keys, modifiers, +or buttons on an extension device. This event is reported to +clients selecting DeviceMappingNotify for the device and window +and is generated after every client SetDeviceButtonMapping, +ChangeDeviceKeyMapping, or ChangeDeviceModifierMapping request. 3.7 ChangeDeviceNotify Event +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - ChangeDeviceNotify - device: CARD8 - time: TIMESTAMP - request: CARD8 + ChangeDeviceNotify + device: CARD8 + time: TIMESTAMP + request: CARD8 - This event reports a change in the physical device being used - as the core X keyboard or X pointer device. ChangeDeviceNotify - events are reported to clients selecting ChangeDeviceNotify for - the device and window and is generated after every client - ChangeKeyboardDevice or ChangePointerDevice request. +This event reports a change in the physical device being used +as the core X keyboard or X pointer device. ChangeDeviceNotify +events are reported to clients selecting ChangeDeviceNotify for +the device and window and is generated after every client +ChangeKeyboardDevice or ChangePointerDevice request. 3.7 Proximity Events - - ProximityIn - ProximityOut - device: CARD8 - root, event: WINDOW - child: Window or None - same-screen: BOOL - root-x, root-y, event-x, event-y: INT16 - state: SETofKEYBUTMASK - time: TIMESTAMP - device-state: SETofKEYBUTMASK - axis-count: CARD8 - first-axis: CARD8 - axis-data: LISTofINT32 - - These events are generated by some devices (such as graphics - tablets or touchscreens) to indicate that a stylus has moved - into or out of contact with a positional sensing surface. - - The “source” of the event is the window the pointer is in. The - window with respect to which the event is normally reported is - found by looking up the hierarchy (starting with the source - window) for the first window on which any client has selected - interest in the event. The actual window used for reporting can - be modified by active grabs and by the focus window.The window - the event is reported with respect to is called the “event” - window. - - The root is the root window of the “source” window, and root-x - and root-y are the pointer coordinates relative to root's - origin at the time of the event. Event is the “event” window. - If the event window is on the same screen as root, then event-x - and event-y are the pointer coordinates relative to the event - window's origin. Otherwise, event-x and event-y are zero. If - the source window is an inferior of the event window, then - child is set to the child of the event window that is an - ancestor of (or is) the source window. Otherwise, it is set to - None. The state component gives the logical state of the - buttons on the core X pointer and modifier keys on the core X - keyboard just before the event. The device-state component - gives the state of the buttons and modifiers on the device - generating the event. +~~~~~~~~~~~~~~~~~~~~ + + ProximityIn + ProximityOut + device: CARD8 + root, event: WINDOW + child: Window or None + same-screen: BOOL + root-x, root-y, event-x, event-y: INT16 + state: SETofKEYBUTMASK + time: TIMESTAMP + device-state: SETofKEYBUTMASK + axis-count: CARD8 + first-axis: CARD8 + axis-data: LISTofINT32 + +These events are generated by some devices (such as graphics +tablets or touchscreens) to indicate that a stylus has moved +into or out of contact with a positional sensing surface. + +The “source” of the event is the window the pointer is in. The +window with respect to which the event is normally reported is +found by looking up the hierarchy (starting with the source +window) for the first window on which any client has selected +interest in the event. The actual window used for reporting can +be modified by active grabs and by the focus window.The window +the event is reported with respect to is called the “event” +window. + +The root is the root window of the “source” window, and root-x +and root-y are the pointer coordinates relative to root's +origin at the time of the event. Event is the “event” window. +If the event window is on the same screen as root, then event-x +and event-y are the pointer coordinates relative to the event +window's origin. Otherwise, event-x and event-y are zero. If +the source window is an inferior of the event window, then +child is set to the child of the event window that is an +ancestor of (or is) the source window. Otherwise, it is set to +None. The state component gives the logical state of the +buttons on the core X pointer and modifier keys on the core X +keyboard just before the event. The device-state component +gives the state of the buttons and modifiers on the device +generating the event. 3.8 DevicePresenceEvents - - Introduced with XI 1.4. - - DevicePresence - time: TIMESTAMP - devchange: BYTE - #x00: DeviceAdded - #x01: DeviceRemoved - #x02: DeviceEnabled - #x03: DeviceDisabled - #x04: DeviceUnrecoverable - #x05: DeviceControlChanged - deviceid: BYTE - control: CARD16 - - DevicePresence events are sent when the server adds or removes, - or enables or disables an input device. The client is expected - to query the server for the list of input devices using the - ListInputDevices request to obtain the updated list of input - devices. DevicePresence events are also sent when a control on - the device has been changed. - - The devchange field specifies the type of operation. In case of - DeviceAdded, a new device has been added to the server, but - this device does not yet send events. If devchange is set to - DeviceEnabled, the device is enabled and will generate events. - If the field is DeviceDisabled or DeviceRemoved, the given - device is disabled and stops sending events or was removed from - the server, respectively. If the field is DeviceUnrecoverable, - an IO-error has occured on the device and the device is - forcibly disabled and removed by the server. If devchange is - DeviceControlChanged, control specifies the type of control - that has been changed. +~~~~~~~~~~~~~~~~~~~~~~~~ + +Introduced with XI 1.4. + + DevicePresence + time: TIMESTAMP + devchange: BYTE + #x00: DeviceAdded + #x01: DeviceRemoved + #x02: DeviceEnabled + #x03: DeviceDisabled + #x04: DeviceUnrecoverable + #x05: DeviceControlChanged + deviceid: BYTE + control: CARD16 + +DevicePresence events are sent when the server adds or removes, +or enables or disables an input device. The client is expected +to query the server for the list of input devices using the +ListInputDevices request to obtain the updated list of input +devices. DevicePresence events are also sent when a control on +the device has been changed. + +The devchange field specifies the type of operation. In case of +DeviceAdded, a new device has been added to the server, but +this device does not yet send events. If devchange is set to +DeviceEnabled, the device is enabled and will generate events. +If the field is DeviceDisabled or DeviceRemoved, the given +device is disabled and stops sending events or was removed from +the server, respectively. If the field is DeviceUnrecoverable, +an IO-error has occured on the device and the device is +forcibly disabled and removed by the server. If devchange is +DeviceControlChanged, control specifies the type of control +that has been changed. 3.9 DevicePropertyNotifyEvent +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Introduced with XI 1.5. +Introduced with XI 1.5. - DevicePropertyNotifyEvent - deviceid: CARD8 - state: CARD8 - time: TIMESTAMP - atom: ATOM + DevicePropertyNotifyEvent + deviceid: CARD8 + state: CARD8 + time: TIMESTAMP + atom: ATOM - A DevicePropertyNotifyEvent is sent to all clients when a - property on the device is created, deleted, or changes value. +A DevicePropertyNotifyEvent is sent to all clients when a +property on the device is created, deleted, or changes value. - The deviceid specifies the device which's property has been - modified. +The deviceid specifies the device which's property has been +modified. - The atom specifies the named identifier of the property that - has been altered. +The atom specifies the named identifier of the property that +has been altered. - If state is PropertyNewValue, the given property has a new - value or has been newly created. If state is PropertyDeleted, - the given property has been deleted. +If state is PropertyNewValue, the given property has a new +value or has been newly created. If state is PropertyDeleted, +the given property has been deleted. |