diff options
| author | Peter Hutterer <peter.hutterer@who-t.net> | 2011-03-23 13:27:02 +1000 |
|---|---|---|
| committer | Peter Hutterer <peter.hutterer@who-t.net> | 2011-03-24 10:06:05 +1000 |
| commit | ab930a51047f48c7befd4316a9b116f37075697f (patch) | |
| tree | e5db9cbecebe90acc34a1f6a0741a021337df195 /specs/XIproto.txt | |
| parent | ef7518cc6260e05a00c496c9e0f3a13c8a785b85 (diff) | |
specs: enable asciidoc parsing for XIproto.txt
The vast majority of this patch are indentation changes, removing preceding
spaces from text.
Header lines and some linebreaks to enable list parsing were added.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Gaetan Nadon <memsize@videotron.ca>
Diffstat (limited to 'specs/XIproto.txt')
| -rw-r--r-- | specs/XIproto.txt | 3724 |
1 files changed, 1882 insertions, 1842 deletions
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. |