[PATCH v2 inputproto] Add minimal asciidoc syntax
Peter Hutterer
peter.hutterer at who-t.net
Tue Mar 15 16:57:10 PDT 2011
Though this protocol description is mainly to be viewed as textfile, a few
minor changes make it parsable for asciidoc to spit out reasonably
nicely-formatted html code.
Changes include:
- underline section headers with the matching lines
- add linebreaks before lists to parse them as lists
- change indentation level for normal text to be left-marging aligned and
for <pre> text to be indented
- comment out section dividers
It's possible to run asciidoc XI2proto.txt and get some nice html output
now.
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
Reviewed-by: Chase Douglas <chase.douglas at canonical.com>
---
Changes to v1:
- change header order one down to avoid asciidoc errors
- Make document name a first-class header
XI2proto.txt | 820 ++++++++++++++++++++++++++++++----------------------------
1 files changed, 429 insertions(+), 391 deletions(-)
diff --git a/XI2proto.txt b/XI2proto.txt
index 10f58c2..5d1b275 100644
--- a/XI2proto.txt
+++ b/XI2proto.txt
@@ -1,5 +1,6 @@
+The X Input Extension
+=====================
- The X Input Extension
Version 2.0
Peter Hutterer
@@ -9,11 +10,13 @@
1. Introduction
+---------------
The X Input Extension version 2.0 (XI2) is the second major release of the X
Input Extension.
XI2 provides a number of enhancements over version 1.5, including:
+
- use of XGE and GenericEvents. GenericEvents are of flexible length with a
minimum length of 32 bytes.
- explicit device hierarchy of master and slave devices. See Section 4.
@@ -31,47 +34,56 @@ used on applications employing the core protocol. XI2 addresses both of these
issues by enabling devices to be both extended and core devices and providing
device information in each event (with the exception of core events).
- ❧❧❧❧❧❧❧❧❧❧❧
+// ❧❧❧❧❧❧❧❧❧❧❧
2. Notations used in this document
+----------------------------------
Notation for requests:
-┌───
- Name of request
- name of request field: type of request field
- name of request field: type of request field
- ▶
- name of reply field: type of reply field
-└───
+
+ ┌───
+ Name of request
+ name of request field: type of request field
+ name of request field: type of request field
+ ▶
+ name of reply field: type of reply field
+ └───
Notation for events:
-┌───
- Name of event
- name of field: type of field
- name of field: type of field
-└───
+
+ ┌───
+ Name of event
+ name of field: type of field
+ name of field: type of field
+ └───
Complex fields are specified in the following notation:
+
name of field: COMPLEXFIELDTYPE
+
or, if multiple of these fields exist:
+
name of field: LISTofCOMPLEXFIELDTYPE
-COMPLEXFIELDTYPE: { name of subfield: type of subfield,
- name of subfield: type of subfield }
+ COMPLEXFIELDTYPE: { name of subfield: type of subfield,
+ name of subfield: type of subfield }
- ❧❧❧❧❧❧❧❧❧❧❧
+// ❧❧❧❧❧❧❧❧❧❧❧
3. Interoperability between version 1.x and 2.0
+-----------------------------------------------
There is little interaction between 1.x and 2.x versions of the X Input
Extension. Clients are requested to avoid mixing XI1.x and XI2 code as much as
possible. Several direct incompatibilities are observable:
3.1 Limitations resulting from different variable ranges
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XI2 provides a larger range for some fields than XI1. As a result, XI1 clients
may not receive data an XI2 client receives.
These fields include:
+
- devices with a deviceid of greater than 127 are invisible to XI1 clients.
- key events and key grabs featuring larger than 255 can only be sent to XI2
clients.
@@ -81,6 +93,7 @@ These fields include:
3.2 Blocking of grabs
+~~~~~~~~~~~~~~~~~~~~~
XI1 grabs are different to XI2 grab and a device may not be grabbed through an
XI2 grab if an XI1 grab is currently active on this device or vice versa.
@@ -89,20 +102,23 @@ not be grabbed with the same modifier combination by an XI2 or XI 1.x client,
respectively.
3.3 Invisibility of Master Devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
XI 1.x was not designed with support for multiple master devices (see Section
4). As a result, only the first master pointer and master keyboard are visible
to XI 1.x clients, all other master devices are invisible and cannot be
accessed from XI 1.x calls.
- ❧❧❧❧❧❧❧❧❧❧❧
+// ❧❧❧❧❧❧❧❧❧❧❧
4. The Master/Slave device hierarchy
+------------------------------------
XI2 introduces a device hierarchy split up into so-called Master Devices (MD)
and Slave Devices (SD).
4.1 Master devices
+~~~~~~~~~~~~~~~~~~
An MD is a virtual device created and managed by the server. MDs may send core
events and XI events. However, an MD does not represent a physical device and
relies on SDs for event generation. MDs come in two forms: as master pointers
@@ -115,12 +131,14 @@ Clients can use this pairing behaviour to implement input paradigms that
require pointer and keyboard interation (e.g. SHIFT + Click).
4.2 Slave devices
+~~~~~~~~~~~~~~~~~
An SD is usually a physical device configured in the server. SDs are not
represented by a cursor or keyboard focus and may be attached to a master
pointer or master keyboard. SDs can only be attached to any master of the same
type (e.g. a physical pointer device can be attached to any master pointer).
If an event is generated by an SD
+
- if the SD is attached to a master pointer, it changes the position and/or
button state of the master pointer.
- if the SD is attached to a master keyboard, it sends events to this
@@ -132,8 +150,10 @@ If an event is generated by an SD
program.
4.3 Event processing for attached slave devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Whenever an SD changes its logical state,
+
- the event is delivered as an XI event to any interested clients. If the
device is floating, event processing stops.
Otherwise, if the device is attached,
@@ -150,6 +170,7 @@ delivered on W. Once an event has been delivered as either XI or core event,
event processing stops.
4.4. The ClientPointer principle
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Many core protocol and some extension requests are ambiguous when multiple
master devices are available (e.g. QueryPointer does not specfy which pointer).
@@ -169,57 +190,63 @@ If the master pointer currently set as ClientPointer for one or more clients is
removed, the server may either unset the ClientPointer setting or change the
ClientPointer to a different master pointer.
- ❧❧❧❧❧❧❧❧❧❧❧
+// ❧❧❧❧❧❧❧❧❧❧❧
+
5. Data types
+-------------
+
+ BUTTONMASK
+ A binary mask defined as (1 << button number).
+ A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.
+
+ DEVICE { DEVICEID, AllDevices, AllMasterDevices }
+ A DEVICE specifies either a DEVICEID or AllDevices or
+ AllMasterDevices.
+
+ DEVICEID { CARD16 }
+ A DEVICEID is a numerical ID for a device currently available in the
+ server. The server may re-use a device ID after a device's removal.
+ The device IDs 0 and 1 are reserved.
+ AllDevices ........ 0
+ AllMasterDevices .. 1
+
+ DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
+ SlaveKeyboard, FloatingSlave }
+ A DEVICEUSE field specifies the current use of a device in the MD/SD
+ device hierarchy. See Section 4 for more information.
+
+ EVENTMASK
+ An EVENTMASK is a binary mask defined as (1 << event type).
+ A SETofEVENTMASK is a binary OR of zero or more EVENTMASK.
+
+ FP1616
+ Fixed point decimal in 16.16 format as one INT16 and one CARD16.
+ The INT16 contains the integral part, the CARD32 the decimal fraction
+ shifted by 16.
+
+ FP3232
+ Fixed point decimal in 32.32 format as one INT32 and one CARD32.
+ The INT32 contains the integral part, the CARD32 the decimal fraction
+ shifted by 32.
+
+ VALUATORMASK
+ A binary mask defined as (1 << valuator number).
+ A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.
+
+// ❧❧❧❧❧❧❧❧❧❧❧
-BUTTONMASK
- A binary mask defined as (1 << button number).
- A SETofBUTTONMASK is a binary OR of zero or more BUTTONMASK.
-
-DEVICE { DEVICEID, AllDevices, AllMasterDevices }
- A DEVICE specifies either a DEVICEID or AllDevices or
- AllMasterDevices.
-
-DEVICEID { CARD16 }
- A DEVICEID is a numerical ID for a device currently available in the
- server. The server may re-use a device ID after a device's removal.
- The device IDs 0 and 1 are reserved.
- AllDevices ........ 0
- AllMasterDevices .. 1
-
-DEVICEUSE { MasterPointer, MasterKeyboard, SlavePointer,
- SlaveKeyboard, FloatingSlave }
- A DEVICEUSE field specifies the current use of a device in the MD/SD
- device hierarchy. See Section 4 for more information.
-
-EVENTMASK
- An EVENTMASK is a binary mask defined as (1 << event type).
- A SETofEVENTMASK is a binary OR of zero or more EVENTMASK.
-
-FP1616
- Fixed point decimal in 16.16 format as one INT16 and one CARD16.
- The INT16 contains the integral part, the CARD32 the decimal fraction
- shifted by 16.
-
-FP3232
- Fixed point decimal in 32.32 format as one INT32 and one CARD32.
- The INT32 contains the integral part, the CARD32 the decimal fraction
- shifted by 32.
-
-VALUATORMASK
- A binary mask defined as (1 << valuator number).
- A SETofVALUATORMASK is a binary OR of zero or more VALUATORMASK.
-
- ❧❧❧❧❧❧❧❧❧❧❧
6. Errors
+---------
Errors are sent using core X error reports.
-Device
- A value for a DEVICE argument does not specify a valid DEVICE.
+ Device
+ A value for a DEVICE argument does not specify a valid DEVICE.
+
+// ❧❧❧❧❧❧❧❧❧❧❧
- ❧❧❧❧❧❧❧❧❧❧❧
7. Requests:
+------------
The server does not guarantee that the length of a reply remains constant in
future revisions of XI2. A client must always retrieve the exact length of the
@@ -230,6 +257,7 @@ XI2. Clients should ignore this data. Padding bytes in XI2 protocol requests
are required to be 0.
7.1 Requests introduced in version 2.0
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
┌───
XIQueryVersion
@@ -240,19 +268,19 @@ are required to be 0.
minor_version: CARD16
└───
- The client sends the highest supported version to the server and the
- server sends the highest version it supports, but no higher than the
- requested version. Major versions changes can introduce incompatibilities
- in existing functionality, minor version changes introduce only backward
- compatible changes. It is the client's responsibility to ensure that the
- server supports a version which is compatible with its expectations.
+The client sends the highest supported version to the server and the
+server sends the highest version it supports, but no higher than the
+requested version. Major versions changes can introduce incompatibilities
+in existing functionality, minor version changes introduce only backward
+compatible changes. It is the client's responsibility to ensure that the
+server supports a version which is compatible with its expectations.
major_version
Major XI2 version.
minor_version
Minor XI2 version.
- If major_version is less than 2, a BadValue error occurs.
+If major_version is less than 2, a BadValue error occurs.
┌───
XIQueryDevice
@@ -296,7 +324,7 @@ are required to be 0.
value: FP3232
resolution: CARD32 }
- XIQueryDevice details information about the requested input devices.
+XIQueryDevice details information about the requested input devices.
devices
The device to list. If devices is AllDevices, all enabled and
@@ -306,7 +334,8 @@ are required to be 0.
num_devices
The number of deviceinfos returned.
- Each deviceinfo is detailed as follows:
+Each deviceinfo is detailed as follows:
+
deviceid
The unique ID of the device. Device IDs may get re-used when a device
is removed.
@@ -334,10 +363,10 @@ are required to be 0.
name
The device's name. padded to a multiple of 4 bytes.
- For all classes, type specifies the device class. Clients are required
- to ignore unknown device classes. The length field specifies the length
- of the class in 4 byte units.
- The following classes may occur only once: ButtonClass, KeyClass
+For all classes, type specifies the device class. Clients are required
+to ignore unknown device classes. The length field specifies the length
+of the class in 4 byte units.
+The following classes may occur only once: ButtonClass, KeyClass
ButtonClass:
type
@@ -394,8 +423,8 @@ are required to be 0.
value
Last published axis value (if mode is absolute).
- An axis in Relative mode may specify min and max as a hint to the
- client. If no min and max information is available, both must be 0.
+An axis in Relative mode may specify min and max as a hint to the
+client. If no min and max information is available, both must be 0.
┌───
XISelectEvents
@@ -420,24 +449,24 @@ are required to be 0.
mask
Event mask. An event mask for an event type T is defined as (1 << T).
- XISelectEvents selects for XI2 events on window.
+XISelectEvents selects for XI2 events on window.
- If num_masks is 0, a BadValue error occurs.
+If num_masks is 0, a BadValue error occurs.
- Each mask sets the (and overwrites a previous) event mask for the DEVICE
- specified through deviceid. The device AllDevices or
- AllMasterDevices is treated as a separate device by server. A client's
- event mask is the union of AllDevices, AllMasterDevices and the
- per-device event mask.
- The removal of device from the server unsets the event masks for the
- device. If an event mask is set for AllDevices or AllMasterDevices, the
- event mask is not cleared on device removal and affects all future
- devices.
+Each mask sets the (and overwrites a previous) event mask for the DEVICE
+specified through deviceid. The device AllDevices or
+AllMasterDevices is treated as a separate device by server. A client's
+event mask is the union of AllDevices, AllMasterDevices and the
+per-device event mask.
+The removal of device from the server unsets the event masks for the
+device. If an event mask is set for AllDevices or AllMasterDevices, the
+event mask is not cleared on device removal and affects all future
+devices.
- If mask_len is 0, the event mask for the given device is cleared.
+If mask_len is 0, the event mask for the given device is cleared.
- The mask for XIHierarchyEvents may only be selected for XIAllDevices.
- Setting it for any other device results in a BadValue error.
+The mask for XIHierarchyEvents may only be selected for XIAllDevices.
+Setting it for any other device results in a BadValue error.
┌───
XIGetSelectedEvents
@@ -454,13 +483,13 @@ are required to be 0.
masks
Selected event masks by this client.
- Masks are returned on a per-device basis, with masks for AllDevices and
- AllMasterDevices returned separately. A client can calculate the
- effective mask for a device with a bitwise OR of the AllDevices, the
- AllMasterDevices and the device-specific mask.
+Masks are returned on a per-device basis, with masks for AllDevices and
+AllMasterDevices returned separately. A client can calculate the
+effective mask for a device with a bitwise OR of the AllDevices, the
+AllMasterDevices and the device-specific mask.
- If num_masks is 0, no events have been selected by this client on the
- given window.
+If num_masks is 0, no events have been selected by this client on the
+given window.
┌───
XIQueryPointer
@@ -480,7 +509,7 @@ are required to be 0.
buttons: SETofBUTTONMASK
└───
- Query a master pointer device for its current position.
+Query a master pointer device for its current position.
root
The root window the pointer is logically on.
@@ -503,8 +532,8 @@ are required to be 0.
buttons
Button state.
- If the device is not a master pointer device or not a floating slave
- pointer, a BadDevice error results.
+If the device is not a master pointer device or not a floating slave
+pointer, a BadDevice error results.
┌───
XIWarpPointer
@@ -519,9 +548,9 @@ are required to be 0.
deviceid: DEVICEID
└───
- WarpPointer moves the pointer of deviceid as if the user had moved
- the pointer. WarpPointer can only be called for MasterPointer and
- FloatingSlave devices.
+WarpPointer moves the pointer of deviceid as if the user had moved
+the pointer. WarpPointer can only be called for MasterPointer and
+FloatingSlave devices.
src_win
If src_window is not None, the move only takes place if src_window
@@ -544,12 +573,12 @@ are required to be 0.
deviceid
The device to warp.
- This request cannot be used to move the pointer outside the confine-to
- window of an active pointer grab. An attempt will only move the pointer as
- far as the closest edge of the confine-to window.
+This request cannot be used to move the pointer outside the confine-to
+window of an active pointer grab. An attempt will only move the pointer as
+far as the closest edge of the confine-to window.
- This request will generate events just as if the user had instantaneously
- moved the pointer.
+This request will generate events just as if the user had instantaneously
+moved the pointer.
┌───
XIChangeCursor
@@ -558,7 +587,7 @@ are required to be 0.
deviceid: DEVICEID
└───
- Change a master pointer's cursor on the specified window.
+Change a master pointer's cursor on the specified window.
window
The window.
@@ -567,19 +596,19 @@ are required to be 0.
deviceid
The master pointer device.
- Whenever device enters a window W, the cursor shape is selected in the
- following order:
- - if the current window has a device cursor C(d) defined for device,
- display this cursor C(d).
- - otherwise, if the current window has a cursor C(w) defined in the core
- protocol's window attributes, display cursor C(w).
- - repeat on parent window until a cursor has been found.
+Whenever device enters a window W, the cursor shape is selected in the
+following order:
+- if the current window has a device cursor C(d) defined for device,
+ display this cursor C(d).
+- otherwise, if the current window has a cursor C(w) defined in the core
+ protocol's window attributes, display cursor C(w).
+- repeat on parent window until a cursor has been found.
- The device cursor for a given window is reset once the window is destroyed
- or the device is removed, whichever comes earlier.
+The device cursor for a given window is reset once the window is destroyed
+or the device is removed, whichever comes earlier.
- If deviceid does not specify a master pointer, a BadDevice error
- is returned.
+If deviceid does not specify a master pointer, a BadDevice error
+is returned.
┌───
XIChangeHierarchy
@@ -616,18 +645,18 @@ are required to be 0.
length: CARD16
deviceid: DEVICEID }
- XIChangeHierarchy allows a client to modify the MD/SD device
- hierarchy (see Section 4).
+XIChangeHierarchy allows a client to modify the MD/SD device
+hierarchy (see Section 4).
num_changes
The number of changes to apply to the current hierarchy.
changes
The list of changes.
- The server processes the changes in the order received from the client and
- applies each requested change immediately. If an error occurs, processing
- stops at the current change and returns the number of successfully applied
- changes in the error.
+The server processes the changes in the order received from the client and
+applies each requested change immediately. If an error occurs, processing
+stops at the current change and returns the number of successfully applied
+changes in the error.
ADDMASTER creates a pair of master devices.
type
@@ -664,8 +693,8 @@ are required to be 0.
return_mode is Attach. If return_mode is Float, return_pointer
and return_keyboard are undefined.
- Removing a master pointer removes the paired master keyboard and vice
- versa.
+Removing a master pointer removes the paired master keyboard and vice
+versa.
ATTACHSLAVE attaches a slave device to a given master device.
type
@@ -691,30 +720,30 @@ are required to be 0.
deviceid: DEVICEID
└───
- Set the ClientPointer for the client owning win to the given device.
+Set the ClientPointer for the client owning win to the given device.
win
Window or client ID.
deviceid
The master pointer or master keyboard that acts as ClientPointer.
- Some protocol requests are ambiguous and the server has to choose a device
- to provide data for a request or a reply. By default, the server will
- choose a client's ClientPointer device to provide the data, unless the
- client currently has a grab on another device. See section 4.4 for more
- details.
+Some protocol requests are ambiguous and the server has to choose a device
+to provide data for a request or a reply. By default, the server will
+choose a client's ClientPointer device to provide the data, unless the
+client currently has a grab on another device. See section 4.4 for more
+details.
- If win is None, the ClientPointer for this client is set to the given
- device. Otherwise, if win is a valid window, the ClientPointer for the
- client owning this window is set to the given device. Otherwise, if win is
- not a valid window but a client with the client mask equal to win exists,
- this client's ClientPointer is set to the given device.
+If win is None, the ClientPointer for this client is set to the given
+device. Otherwise, if win is a valid window, the ClientPointer for the
+client owning this window is set to the given device. Otherwise, if win is
+not a valid window but a client with the client mask equal to win exists,
+this client's ClientPointer is set to the given device.
- If deviceid does not specify a master pointer or master keyboard, a
- BadDevice error is returned.
+If deviceid does not specify a master pointer or master keyboard, a
+BadDevice error is returned.
- If window does not specify a valid window or client ID and is not None, a
- BadWindow error is returned.
+If window does not specify a valid window or client ID and is not None, a
+BadWindow error is returned.
┌───
XIGetClientPointer
@@ -724,7 +753,7 @@ are required to be 0.
deviceid: DEVICEID
└───
- Query the ClientPointer for the client owning win.
+Query the ClientPointer for the client owning win.
win
The window or client ID.
@@ -733,9 +762,9 @@ are required to be 0.
deviceid
The master pointer that acts as a ClientPointer if set is True.
- No difference is made between a ClientPointer set explicitly through
- XISetClientPointer and a ClientPointer implicitly assigned by the server
- in response to an ambiguous request.
+No difference is made between a ClientPointer set explicitly through
+XISetClientPointer and a ClientPointer implicitly assigned by the server
+in response to an ambiguous request.
┌───
XISetFocus
@@ -744,9 +773,9 @@ are required to be 0.
time: Time
└───
- Set the focus for the given device to the given window. Future key events
- from this device are sent to this window.
- This request generates FocusIn and FocusOut events.
+Set the focus for the given device to the given window. Future key events
+from this device are sent to this window.
+This request generates FocusIn and FocusOut events.
focus
A viewable window or None.
@@ -755,17 +784,17 @@ are required to be 0.
time
Specifies the time to change the focus or CurrentTime.
- If focus is None, key events from this device are discarded until a new
- focus window is set. If focus is a viewable window, key events from this
- device are sent to this window. If the window becomes unviewable, the
- window's first viewable ancestor automatically becomes the focus window
- and FocusIn and FocusOut events are sent as if a client had changed the
- focus window.
- This is equivalent to RevertToParent in the core XSetInputFocus window.
+If focus is None, key events from this device are discarded until a new
+focus window is set. If focus is a viewable window, key events from this
+device are sent to this window. If the window becomes unviewable, the
+window's first viewable ancestor automatically becomes the focus window
+and FocusIn and FocusOut events are sent as if a client had changed the
+focus window.
+This is equivalent to RevertToParent in the core XSetInputFocus window.
- This request has no effect if the specified time is earlier than the
- current 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.
+This request has no effect if the specified time is earlier than the
+current 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.
┌───
XIGetFocus
@@ -774,7 +803,7 @@ are required to be 0.
focus: Window
└───
- Return the current focus window for the given device.
+Return the current focus window for the given device.
┌───
XIGrabDevice
@@ -791,10 +820,10 @@ are required to be 0.
status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable
└───
- 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 overides any previous active grab by this client for this
- device.
+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 overides any previous active grab by this client for this
+device.
deviceid
The device to grab.
@@ -819,40 +848,41 @@ are required to be 0.
status
Success or the reason why the grab could not be established.
- The masks parameter specifies which events the client wishes to receive
- while the device is grabbed.
-
- 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 grab-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 grab-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 XIAllowEvents 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 the device is a slave device, the paired-device-mode is ignored.
- Otherwise, if this device is a master device and paired-device-mode is
- Asynchronous, event processing is unaffected by activation of the grab. If
- this device is a master device and paired-device-mode is Synchronous, the
- state of the master device paired with this device (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 XIAllowEvents 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.
-
- If the cursor is not None and the device is a master pointer device, the
- cursor will be displayed until the device is ungrabbed.
-
- This request fails and returns:
+The masks parameter specifies which events the client wishes to receive
+while the device is grabbed.
+
+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 grab-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 grab-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 XIAllowEvents 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 the device is a slave device, the paired-device-mode is ignored.
+Otherwise, if this device is a master device and paired-device-mode is
+Asynchronous, event processing is unaffected by activation of the grab. If
+this device is a master device and paired-device-mode is Synchronous, the
+state of the master device paired with this device (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 XIAllowEvents 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.
+
+If the cursor is not None and the device is a master pointer device, the
+cursor will be displayed until the device is ungrabbed.
+
+This request fails and returns:
+
AlreadyGrabbed: If the device is actively grabbed by some other client.
NotViewable: If grab-window is not viewable.
InvalidTime: If the specified time is earlier than the last-grab-time for
@@ -862,7 +892,7 @@ are required to be 0.
current X server time.
Frozen: If the device is frozen by an active grab of another client.
- To release a grab of a device, use XIUngrabDevice.
+To release a grab of a device, use XIUngrabDevice.
┌───
XIUngrabDevice
@@ -870,21 +900,21 @@ are required to be 0.
time: TIMESTAMP or CurrentTime
└───
- This request releases the device if this client has it actively grabbed
- (from either XIGrabDevice or XIPassiveGrabDevice) and
- releases any queued events. If any devices were frozen by the grab,
- XIUngrabDevice thaws them.
+This request releases the device if this client has it actively grabbed
+(from either XIGrabDevice or XIPassiveGrabDevice) and
+releases any queued events. If any devices were frozen by the grab,
+XIUngrabDevice thaws them.
deviceid
The device to grab.
time
A valid server time or CurrentTime.
- 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 FocusIn and FocusOut events.
- An XIUngrabDevice is performed automatically if the event window for an
- active device grab becomes not viewable.
+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 FocusIn and FocusOut events.
+An XIUngrabDevice is performed automatically if the event window for an
+active device grab becomes not viewable.
┌───
XIAllowEvents:
@@ -895,8 +925,8 @@ are required to be 0.
ReplayDevice, AsyncPair, SyncPair }
└───
- The XIAllowEvents request releases some queued events if the client
- has caused a device to freeze.
+The XIAllowEvents request releases some queued events if the client
+has caused a device to freeze.
deviceid
The device to grab.
@@ -906,12 +936,13 @@ are required to be 0.
Specifies whether a device is to be thawed and events are to be
replayed.
- 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 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:
AsyncDevice:
If the specified device is frozen by the client, event processing for that
device continues as usual. If the device is frozen multiple times by the
@@ -1004,8 +1035,8 @@ are required to be 0.
GRABMODIFIERINFO { status: Access
modifiers: CARD32 }
- Establish an explicit passive grab for a button or keycode
- on the specified input device.
+Establish an explicit passive grab for a button or keycode
+on the specified input device.
cursor
The cursor to display for the duration of the grab. If grab_type
@@ -1046,27 +1077,28 @@ are required to be 0.
modifiers_return
XKB modifier state that could not be grabbed.
- 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 deviceid specifies a master pointer, the modifiers of the paired
- master keyboard are used. If deviceid specifies a slave pointer
- the modifiers of the master keyboard paired with the attached master
- pointers are used. If deviceid specifies a slave keyboard, the
- modifiers of the attached master keyboard are used. Note that
- activating a grab on a slave device detaches the device from its
- master. In this case, the modifiers after activation of the grab are
- from the slave device only and may be different to the modifier state
- when the grab was triggered.
-
- In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the
- device is actively grabbed if:
+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 deviceid specifies a master pointer, the modifiers of the paired
+master keyboard are used. If deviceid specifies a slave pointer
+the modifiers of the master keyboard paired with the attached master
+pointers are used. If deviceid specifies a slave keyboard, the
+modifiers of the attached master keyboard are used. Note that
+activating a grab on a slave device detaches the device from its
+master. In this case, the modifiers after activation of the grab are
+from the slave device only and may be different to the modifier state
+when the grab was triggered.
+
+In the future, if grab_type is GrabtypeButton or GrabtypeKeyboard, the
+device is actively grabbed if:
+
- the device is not grabbed, and
- the specified modifier keys are down, and
- the grab_type is GrabtypeButton and the button specified in detail
@@ -1076,8 +1108,9 @@ are required to be 0.
- a passive grab on the same button/keycode + modifier
combination does not exist on an ancestor of grab_window.
- Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the
- device is actively grabbed if:
+Otherwise, if grab_type is GrabtypeEnter or GrabtypeFocusIn, the
+device is actively grabbed if:
+
- the device is not actively grabbed, and
- the specified modifier keys are down, and
- the grab_type is GrabtypeEnter and the device's pointer has moved
@@ -1087,51 +1120,51 @@ are required to be 0.
- a passive grab of the same grab_type + modifier combination does not
does not exist on an ancestor of grab_window.
- A modifier of GrabAnyModifier is equivalent to issuing the request for
- all possible modifier combinations (including no modifiers). A client
- may request a grab for GrabAnyModifier and explicit modifier
- combinations in the same request.
-
- A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons
- or keycode are released, independent of the state of modifier keys.
- A GrabtypeEnter or GrabtypeFocusIn grab is released when the
- pointer or focus leaves the window and all of its descendants,
- independent of the state of modifier keys.
- Note that the logical state of a device (as seen by means of the
- protocol) may lag the physical state if device event processing is
- frozen.
-
- This request overrides all previous passive grabs by the same
- client on the same button/key/enter/focus in + modifier combinations
- on the same window.
-
- If some other client already has issued a XIPassiveGrabDevice request
- with the same button or keycode and modifier combination, the
- failed modifier combinations is returned in modifiers_return. If some
- other client already has issued an XIPassiveGrabDevice request of
- grab_type XIGrabtypeEnter or XIGrabtypeFocusIn with the same
- grab_window and the same modifier combination, the failed modifier
- combinations are returned in modifiers_return. If num_modifiers_return
- is zero, all passive grabs have been successful.
-
- If a button grab or enter grab activates, EnterNotify and LeaveNotify
- events with mode Grab are generated as if the pointer were to suddenly
- warp from its current position some position in the grab_window.
- However, the pointer does not warp, and the pointer position is used
- as both the initial and final positions for the events.
-
- If a keycode grab or focus grab activates, FocusIn and FocusOut events
- with mode Grab are generated as if the focus were to change from the
- current window to the grab_window.
-
- If an enter or focus in grab activates, additional EnterNotify events
- with mode XIPassiveGrabNotify are generated as if the pointer or focus
- were to suddenly warp from its current position to some position in
- the grab window. These events are sent to the grabbing client only
- and only if the grab event mask has selected for it. If such a passive
- grab deactivates, addional LeaveNotify events with mode
- XIPassiveUngrabNotify are generated and sent to the grabbing client
- before the grab deactivates.
+A modifier of GrabAnyModifier is equivalent to issuing the request for
+all possible modifier combinations (including no modifiers). A client
+may request a grab for GrabAnyModifier and explicit modifier
+combinations in the same request.
+
+A GrabtypeButton or GrabtypeKeyboard grab is released when all buttons
+or keycode are released, independent of the state of modifier keys.
+A GrabtypeEnter or GrabtypeFocusIn grab is released when the
+pointer or focus leaves the window and all of its descendants,
+independent of the state of modifier keys.
+Note that the logical state of a device (as seen by means of the
+protocol) may lag the physical state if device event processing is
+frozen.
+
+This request overrides all previous passive grabs by the same
+client on the same button/key/enter/focus in + modifier combinations
+on the same window.
+
+If some other client already has issued a XIPassiveGrabDevice request
+with the same button or keycode and modifier combination, the
+failed modifier combinations is returned in modifiers_return. If some
+other client already has issued an XIPassiveGrabDevice request of
+grab_type XIGrabtypeEnter or XIGrabtypeFocusIn with the same
+grab_window and the same modifier combination, the failed modifier
+combinations are returned in modifiers_return. If num_modifiers_return
+is zero, all passive grabs have been successful.
+
+If a button grab or enter grab activates, EnterNotify and LeaveNotify
+events with mode Grab are generated as if the pointer were to suddenly
+warp from its current position some position in the grab_window.
+However, the pointer does not warp, and the pointer position is used
+as both the initial and final positions for the events.
+
+If a keycode grab or focus grab activates, FocusIn and FocusOut events
+with mode Grab are generated as if the focus were to change from the
+current window to the grab_window.
+
+If an enter or focus in grab activates, additional EnterNotify events
+with mode XIPassiveGrabNotify are generated as if the pointer or focus
+were to suddenly warp from its current position to some position in
+the grab window. These events are sent to the grabbing client only
+and only if the grab event mask has selected for it. If such a passive
+grab deactivates, addional LeaveNotify events with mode
+XIPassiveUngrabNotify are generated and sent to the grabbing client
+before the grab deactivates.
┌───
XIPassiveUngrabDevice
@@ -1143,7 +1176,7 @@ are required to be 0.
modifiers: MODIFIERINFO
└───
- Release an explicit passive grab on the specified input device.
+Release an explicit passive grab on the specified input device.
deviceid
The device to establish the passive grab on.
@@ -1159,9 +1192,9 @@ are required to be 0.
num_modifiers
Number of elements in modifiers.
- This request has no effect if the client does not have a passive grab
- of the same type, same button or keycode (if applicable) and modifier
- combination on the grab_window.
+This request has no effect if the client does not have a passive grab
+of the same type, same button or keycode (if applicable) and modifier
+combination on the grab_window.
┌───
XIListProperties
@@ -1171,7 +1204,7 @@ are required to be 0.
properties: LISTofATOM
└───
- List the properties associated with the given device.
+List the properties associated with the given device.
deviceid
The device to list the properties for.
@@ -1191,7 +1224,7 @@ are required to be 0.
data: LISTofINT8, or LISTofINT16, or LISTofINT32
└───
- Change the given property on the given device.
+Change the given property on the given device.
deviceid
The device to change the property on.
@@ -1206,26 +1239,26 @@ are required to be 0.
data
Property data (nitems * format/8 bytes)
- The type is uninterpreted by the server. The format specifies whether
- the data should be viewed as a list of 8-bit, 16-bit, or 32-bit
- quantities so that the server can correctly byte-swap as necessary.
+The type is uninterpreted by the server. The format specifies whether
+the data should be viewed as a list of 8-bit, 16-bit, or 32-bit
+quantities so that the server can correctly byte-swap as necessary.
- If the mode is Replace, the previous propert y value is discarded. If
- the mode is Prepend or Append, then the type and format must match the
- existing property value (or a Match error results). If the property is
- undefined, it is treated as defined with the correct type and format
- with zero-length data. For Prepend, the data is tacked on to the
- beginning of the existing data, and for Append, it is tacked on to the
- end of the existing data.
+If the mode is Replace, the previous propert y value is discarded. If
+the mode is Prepend or Append, then the type and format must match the
+existing property value (or a Match error results). If the property is
+undefined, it is treated as defined with the correct type and format
+with zero-length data. For Prepend, the data is tacked on to the
+beginning of the existing data, and for Append, it is tacked on to the
+end of the existing data.
- The lifetime of a property is not tied to the storing client. Properties
- remain until explicitly deleted, until the device is removed, or
- until server reset.
+The lifetime of a property is not tied to the storing client. Properties
+remain until explicitly deleted, until the device is removed, or
+until server reset.
- A property cannot be deleted by setting nitems to zero. To delete a
- property, use XIDeleteProperty.
+A property cannot be deleted by setting nitems to zero. To delete a
+property, use XIDeleteProperty.
- This request generates an XIPropertyEvent.
+This request generates an XIPropertyEvent.
┌───
XIDeleteProperty
@@ -1233,15 +1266,15 @@ are required to be 0.
property: ATOM
└───
- Deletes the given property on the given device.
+Deletes the given property on the given device.
deviceid
The device to delete the property on.
property
The property to delete.
- If the property is deleted, an XIPropertyEvent is generated on the device.
- If the property does not exist, this request does nothing.
+If the property is deleted, an XIPropertyEvent is generated on the device.
+If the property does not exist, this request does nothing.
┌───
XIGetProperty
@@ -1259,7 +1292,7 @@ are required to be 0.
data: LISTofINT8, or LISTofINT16, or LISTofINT32
└───
- Get the data for the given property on the given device.
+Get the data for the given property on the given device.
deviceid
The device to retrieve the property data from.
@@ -1282,34 +1315,37 @@ are required to be 0.
data
Property data (nitems * format/8 bytes)
- If the specified property does not exist for the specified device, then
- the return type is None, the format and bytes-after are zero, and the value is
- empty. The delete argument is ignored in this case. If the specified property
- exists but its type does not match the specified type, then the return
- type is the actual type of the property, the format is the actual format of the
- property (never zero), the bytes-after is the length of the property in bytes
- (even if the format is 16 or 32), and the value is empty. The delete
- argument is ignored in this case. If the specified property exists and
- either AnyPropertyType is specified or the specified type matches the actual
- type of the property, then the return type is the actual type of the property,
- the format is the actual format of the property
- (never zero), and the bytes-after and value are as follows, given:
- N = actual length of the stored property in bytes
- (even if the format is 16 or 32)
- I = 4 * long-offset
- T = N−I
- L = MINIMUM(T, 4 * long-length)
- A = N − (I + L)
- The returned value starts at byte index I in the property (indexing
- from 0), and its length in bytes is L. However, it is a Value error if
- offset is given such that L is negative. The value of bytes_after is A,
- giving the number of trailing unread bytes in the stored property. If
- delete is True and the bytes_after is zero, the property is also
- deleted from the device, and a XIPropertyNotify event is generated on
- the device.
+If the specified property does not exist for the specified device, then
+the return type is None, the format and bytes-after are zero, and the value is
+empty. The delete argument is ignored in this case. If the specified property
+exists but its type does not match the specified type, then the return
+type is the actual type of the property, the format is the actual format of the
+property (never zero), the bytes-after is the length of the property in bytes
+(even if the format is 16 or 32), and the value is empty. The delete
+argument is ignored in this case. If the specified property exists and
+either AnyPropertyType is specified or the specified type matches the actual
+type of the property, then the return type is the actual type of the property,
+the format is the actual format of the property
+(never zero), and the bytes-after and value are as follows, given:
+
+ N = actual length of the stored property in bytes
+ (even if the format is 16 or 32)
+ I = 4 * long-offset
+ T = N−I
+ L = MINIMUM(T, 4 * long-length)
+ A = N − (I + L)
+
+The returned value starts at byte index I in the property (indexing
+from 0), and its length in bytes is L. However, it is a Value error if
+offset is given such that L is negative. The value of bytes_after is A,
+giving the number of trailing unread bytes in the stored property. If
+delete is True and the bytes_after is zero, the property is also
+deleted from the device, and a XIPropertyNotify event is generated on
+the device.
8. Events:
+----------
An event specifies its length in 4-byte units after the initial 32 bytes.
Future versions of the protocol may provide additional information
@@ -1342,13 +1378,13 @@ Version 2.0:
All events have a set of common fields specified as EVENTHEADER.
-EVENTHEADER { type: BYTE
- extension: BYTE
- sequenceNumber: CARD16
- length: CARD32
- evtype: CARD16
- deviceid: DEVICEID
- time: Time }
+ EVENTHEADER { type: BYTE
+ extension: BYTE
+ sequenceNumber: CARD16
+ length: CARD32
+ evtype: CARD16
+ deviceid: DEVICEID
+ time: Time }
type
Always GenericEvent.
@@ -1391,26 +1427,27 @@ EVENTHEADER { type: BYTE
info:
The current hierarchy information.
- An XIHierarchyEvent is sent whenever the device hierarchy been
- changed. The flags specify all types of hierarchy modifiations that have
- occured.
- For all devices, info details the hierarchy information after the
- modification of the hierarchy has occured. For each device specified with
- deviceid:
- - if type is MasterPointer or MasterKeyboard, attachment decribes the
- pairing of this device.
- - if type is SlavePointer or SlaveKeyboard, attachment describes the
- master device this device is attached to.
- - if type is FloatingSlave device, attachment is undefined.
+An XIHierarchyEvent is sent whenever the device hierarchy been
+changed. The flags specify all types of hierarchy modifiations that have
+occured.
+For all devices, info details the hierarchy information after the
+modification of the hierarchy has occured. For each device specified with
+deviceid:
+
+- if type is MasterPointer or MasterKeyboard, attachment decribes the
+ pairing of this device.
+- if type is SlavePointer or SlaveKeyboard, attachment describes the
+ master device this device is attached to.
+- if type is FloatingSlave device, attachment is undefined.
enabled
True if the device is enabled and can send events. A disabled master
device will not forward events from an attached, enabled slave
device.
- Note: Multiple devices may be affected in one hierarchy change,
- deviceid in an XIHierarchyEvent is always the first affected
- device. Clients should ignore deviceid and instead use the devices list.
+Note: Multiple devices may be affected in one hierarchy change,
+deviceid in an XIHierarchyEvent is always the first affected
+device. Clients should ignore deviceid and instead use the devices list.
┌───
DeviceChangedEvent:
@@ -1423,9 +1460,9 @@ EVENTHEADER { type: BYTE
CHANGEREASON { SlaveSwitch, DeviceChange }
- A DeviceChangeEvent is sent whenever a device changes it's capabilities.
- This can happen either by a new slave device sending events through a
- master device, or by a physical device changing capabilities at runtime.
+A DeviceChangeEvent is sent whenever a device changes it's capabilities.
+This can happen either by a new slave device sending events through a
+master device, or by a physical device changing capabilities at runtime.
reason
The reason for generating this event.
@@ -1443,7 +1480,7 @@ EVENTHEADER { type: BYTE
Details the available classes provided by the device. The order the
classes are provided in is undefined.
- For a detailed description of classes, see the XQueryDevice request.
+For a detailed description of classes, see the XQueryDevice request.
┌───
DeviceEvent:
@@ -1483,10 +1520,10 @@ EVENTHEADER { type: BYTE
DEVICEEVENTFLAGS (key events only): { KeyRepeat }
DEVICEEVENTFLAGS (pointer events only): none
- An XIDeviceEvent is generated whenever the logical state of a device
- changes in response to a button press, a button release, a motion, a key
- press or a key release. The event type may be one of KeyPress,
- KeyRelease, ButtonPress, ButtonRelease, Motion.
+An XIDeviceEvent is generated whenever the logical state of a device
+changes in response to a button press, a button release, a motion, a key
+press or a key release. The event type may be one of KeyPress,
+KeyRelease, ButtonPress, ButtonRelease, Motion.
detail
The button number or key code, or 0.
@@ -1527,7 +1564,8 @@ EVENTHEADER { type: BYTE
the physical state of the key has not changed. This is only
valid for KeyPress events.
- Modifier state in mods is detailed as follows:
+Modifier state in mods is detailed as follows:
+
base_mods
XKB base modifier state.
latched_mods
@@ -1554,14 +1592,14 @@ EVENTHEADER { type: BYTE
axisvalues_raw: LISTofFP3232
└───
- A RawEvent provides the information provided by the driver to the
- client. RawEvent provides both the raw data as supplied by the driver and
- transformed data as used in the server. Transformations include, but are
- not limited to, axis clipping and acceleration.
- Transformed valuator data may be equivalent to raw data. In this case,
- both raw and transformed valuator data is provided.
- RawEvents are sent exclusively to all root windows or to the client
- that grabbed the device only.
+A RawEvent provides the information provided by the driver to the
+client. RawEvent provides both the raw data as supplied by the driver and
+transformed data as used in the server. Transformations include, but are
+not limited to, axis clipping and acceleration.
+Transformed valuator data may be equivalent to raw data. In this case,
+both raw and transformed valuator data is provided.
+RawEvents are sent exclusively to all root windows or to the client
+that grabbed the device only.
eventtype
The type of event that occured on the device.
@@ -1603,22 +1641,22 @@ EVENTHEADER { type: BYTE
NOTIFYDETAIL { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual,
Pointer, PointerRoot, None }
- Enter or Leave events are sent whenever a device's pointer enters or
- leaves a window.
- FocusIn or FocusOut events are sent whenever a device's focus is set to or
- away from a window.
- The enter/leave and focus in/out model is described in the core protocol
- specification, Section 11. (EnterNotify, LeaveNotify events).
+Enter or Leave events are sent whenever a device's pointer enters or
+leaves a window.
+FocusIn or FocusOut events are sent whenever a device's focus is set to or
+away from a window.
+The enter/leave and focus in/out model is described in the core protocol
+specification, Section 11. (EnterNotify, LeaveNotify events).
- For enter and leave events, the modifier and group state is the state of
- the paired master device if the device is a master device, or the state of
- the attached master keyboard if the device is an attached slave device, or
- zero if the device is a floating slave device.
+For enter and leave events, the modifier and group state is the state of
+the paired master device if the device is a master device, or the state of
+the attached master keyboard if the device is an attached slave device, or
+zero if the device is a floating slave device.
- For focus in and out events, the button state is the state of the paired
- master device if the device is a master device, or the state of the
- attached master keyboard if the device is an attached slave device, or
- zero if the device is a floating slave device.
+For focus in and out events, the button state is the state of the paired
+master device if the device is a master device, or the state of the
+attached master keyboard if the device is an attached slave device, or
+zero if the device is a floating slave device.
root
event
@@ -1665,8 +1703,8 @@ EVENTHEADER { type: BYTE
what: { PropertyCreated, PropertyDeleted, PropertyModified }
└───
- XIPropertyEvents are sent whenever a device property is created, deleted or
- modified by a client.
+XIPropertyEvents are sent whenever a device property is created, deleted or
+modified by a client.
property
The property that has been created, deleted, or modified
@@ -1674,4 +1712,4 @@ EVENTHEADER { type: BYTE
Specifies what has been changed.
- ❧❧❧❧❧❧❧❧❧❧❧
+// ❧❧❧❧❧❧❧❧❧❧❧
--
1.7.4
More information about the xorg-devel
mailing list