diff options
| author | Peter Hutterer <peter.hutterer@who-t.net> | 2009-10-02 11:50:23 +1000 |
|---|---|---|
| committer | Alan Coopersmith <alan.coopersmith@sun.com> | 2009-10-01 20:34:04 -0700 |
| commit | f0299dace37eb111bcc09cf6578bb4b16c874c7d (patch) | |
| tree | 5e51bf924bcbb6bcb6ebfc845f626a72b99d99d1 | |
| parent | f7fe7beb7a4d0509a23ffc34a4a5739b28d82850 (diff) | |
Remove out-dated XI2 stuff from Xi protocol spec.
The protocol spec here represents the state after the MPX merge and has
changed considerably since. The new spec is over in the inputproto module.
Signed-off-by: Peter Hutterer <peter.hutterer@who-t.net>
Reviewed-by: Alan Coopersmith <alan.coopersmith@sun.com>
| -rw-r--r-- | specs/Xi/protocol.xml | 921 |
1 files changed, 6 insertions, 915 deletions
diff --git a/specs/Xi/protocol.xml b/specs/Xi/protocol.xml index 3669647..9db1734 100644 --- a/specs/Xi/protocol.xml +++ b/specs/Xi/protocol.xml @@ -14,9 +14,6 @@ X Version 11, Release 6.8 Mark Patrick, Ardent Computer George Sachs, Hewlett-Packard - - Version 2.0 - Peter Hutterer, University of South Australia </emphasis> </literallayout> </para> @@ -78,26 +75,6 @@ the additional input devices. </para> </sect2> - <sect2> - <title>Input Extension Versions</title> - <para> - This document includes the specifications for X Input - Extension Version 1.x and X Input Version 2.x (XI2). The - differences for each version are spelled out in the respective - descriptions for requests and events. - </para> - <para> - There are three notable versions of XI. Most of this document - describes the behaviour of the Input Extension 1.0, 1.1, 1.2, - and 1.2. XI 1.4 introduced virtual devices that act as core - devices (see <xref linkend='core_input_devices'/>) and input - device hotplugging. XI 1.5 introduced device properties. - XI 2.0 introduces the ability to create - multiple virtual core devices. Unless stated otherwise, the - content of this document applies to all versions of the Input - Extension. - </para> - </sect2> <sect2 id='design_approach'> <title>Design Approach</title> <para>The design approach of the extension is to define requests @@ -123,10 +100,8 @@ <para> 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 XI 2.0 and - above, multiple core pointers and core keyboards may exist, - but for each core pointer there must be one core keyboard. No - odd number of core devices is possible. + physical device connected to the host computer. + No odd number of core devices is possible. </para> <para>The X keyboard and X pointer are referred to in this document as the <emphasis remap='I'>core devices</emphasis>, @@ -153,19 +128,13 @@ core devices is left implementation-dependent. Requests are defined that allow client programs to change which physical devices are used as the core devices.</para> - <para> - In servers supporting XI 2.0 and above, core devices are also - exteension devices and generate both core and input extension - events. For a detailed description of the handling of input - devices in XI 2.0 and above, see <xref linkend='xi2_device_handling'/>.</para> </sect2> <sect2 id='extension_input_devices'> <title>Extension Input Devices</title> <para>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. XI 2.0 and above also enable access to the X keyboard - and the X pointer. + devices. </para> <para>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 @@ -207,10 +176,6 @@ not explicitly focused, their focus is determined by the location of the core X pointer. </para> - <para> - In XI 2.x, the location and focus of an extension input device - is determined by its attachment. See <xref linkend="xi2_device_handling"/>. - </para> <para>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 @@ -302,149 +267,6 @@ these requests to be recompiled.</para> </sect3> </sect2> - <sect2 id='xi2_device_handling'> - <title>XI 2.0 device handling</title> - <para>XI Version 2.0 introduces a device hierarchy split up into - so-called "Master Devices" (MD) and "Slave - Devices" (SD). This distinction is key to both the device - handling and the event handling in the server.</para> - <para>An MD is always a virtual device and does not represent a - physical device connected to the host computer. MDs come in - two forms: as master pointers or as master keyboards. - A master pointer is reflected by a visible cursor on the - screen. A master keyboard is reflected by a keyboard focus. - </para> - <para> - Each master pointer is "paired" with the respective - master keyboard and vice versa, and this pairing is maintained - for the lifetime of both input devices. Clients can utilise - this pairing behaviour to implement combinatory input - paradigms such as SHIFT + Click. For a description on how to - obtain this pairing, see <xref linkend="listing_available_devices"/>. - </para> - <para> - MDs may send core events and XI events. However, as an MD does - not represent a physical device, they rely on SDs for event - generation. - </para> - <para> - An SD is a physical device configured in the server. SDs are - not represented by a cursor or keyboard focus. An SD may be - "attached" to a master pointer or master keyboard. - In this case, each event generated by the SD is - <emphasis>also</emphasis> routed through the MD. Such an event - is modified inside the server and appears to the client as if - generated by the MD. See <xref linkend="xi2_event_processing"/> - for more details. - </para> - <para>SDs can only send XI events.</para> - <para> - <example width='3in'> - <title>Example device setup</title> - <para>A server may have two master devices (one master pointer - and one master keyboard). It thus displays one cursor and - provides one keyboard focus.</para> - <para>One mouse and one keyboard are connected to the server. - The server thus controls two slave devices. The mouse is - attached to the master pointer and the keyboard to the - master keyboard.</para> - <para>When the mouse moves, the matching slave device - generates an XI event. This event is processed until - delivered. After that, the same event is modified to - appear as being generated by the master pointer. This - modified event is then processed until delivered. To a - client, the latter event appears to be coming from the - master pointer.</para> - </example> - </para> - <sect3 id='xi2_attachment'> - <title>Attachment of slave devices</title> - <para> - SDs can be attached to any master of the same type (e.g. a - physical pointer device can be attached to any master - pointer). In this case, the SD controls the MDs cursor and - a movement of the SD will change the cursor position of - this MD. Likewise, an attached keyboard device shares the - keyboard focus of the respective master keyboard. - </para> - <para> - SDs can be "floating", in which case they are - not attached to an MD. Such a floating devices does not - route events through any MD and does not have a visible - cursor. The focus of such a floating device must be - explicitly controlled by the client program. - </para> - </sect3> - <sect3 id='xi2_event_processing'> - <title>Event processing for attached slave devices</title> - <para> - If an SD generates an event, this event is processed as - normal and delivered to any client that previously - registered for the respective event type. Such events are - always input extension events and the SD can be identified - by the device identifier in event. - </para> - <para> - After the SD's event has been processed, the event's - device identifier is modified and set to the SD's master - device. The event is then processed again, this time - appearing as if generated by the master device. - During event processing, a core event is generated from - the input extension event. If the core event is delivered - to a client, the input extension event is not processed - further and the server continues with the next input - event. Only if the core event is not delivered may the - input extension event be delivered to a client. - </para> - <para> - Before the MD's event is processed, the MD switches state - to represent the capabilities of the SD. As previously - described in <xref linkend="input_classes"/>, each SD - describes its capabilities through a number of input - classes. When the MD switches state, it duplicates the - input classes of the SD and thus appears to have the same - capabilities as the SD. Clients are notified of this - switch. - </para> - <para> - <example width='3in'> - <title>Event routing with two pointer devices.</title> - <para> - A server has a traditional USB mouse and a - graphics tablet attached. The USB mouse provides 3 - buttons and relative x/y axes. The graphics tablet - provides 8 buttons and 3 absolute axes in a - device-specific coordinate system. - Both devices are attached to the same master - pointer. - </para> - <para> - When the mouse generates an event, this input - extension event is delivered as normal. The event - is then modified to appear as being generated by - the master pointer. The master pointer modifies - its input classes to appear as a device that - provides 3 buttons and two relative axes. The - input extension event is then processed. - A core event may be delivered instead of the input - extension event. - </para> - <para> - When the graphics tablet generates an event, this - input extension event is deliveredd as normal. The - event is ethen modified to appear as being - generated by the master pointer. The master - pointer modifies its input classes to appear as a - devices that provides 8 buttons and thre absolute - axes in a device-specific coordinate system. The - input extension event is then processed, and a - core event may be delivered instead of the input - extension event. - </para> - </example> - </para> - </sect3> - </sect2> </sect1> <sect1 id='requests'> <title>Requests</title> @@ -459,8 +281,6 @@ <literallayout> GetExtensionVersion name: STRING - client-major-version: CARD8 - client-minor-version: CARD8 => present: BOOL protocol-major-version: CARD16 @@ -472,22 +292,8 @@ <filename>XI.h</filename>. Each version is a superset of the previous versions.</para> <para> - For clients supporting XI 1.x only, the name must be the - name of the Input Extension as defined in the header - file <filename>XI.h</filename>. client-major-version and - client-minor-version are undefined. - For clients supporting XI 2.0 and above, the name must be of - zero length and client-major-version and client-minor version - must reflect the Input Extension version as supported by the - client. - The server changes the behaviour of some requests depending on - the version supported by the client. A client that does not - specify support for XI 2.x cannot use the extended - functionality of this version. - </para> - <para> - client-major-version and client-minor-version are CARD8 to - ensure binary compatibility with pre-XI 2.0 implementations. + The name must be the name of the Input Extension as defined in the header + file <filename>XI.h</filename>. </para> </sect2> <sect2 id='listing_available_devices'><title>Listing Available Devices</title> @@ -496,11 +302,6 @@ is done through the <emphasis>ListInputDevices</emphasis> request, which will return a list of all devices that can be opened by the X server. - For clients that have not announced XI 2.x support through the - <emphasis>GetExtensionVersion</emphasis> request, - <emphasis>ListInputDevices</emphasis> only returns the first - master pointer, the first master keyboard, and all floating - slave devices. <literallayout> ListInputDevices => @@ -514,7 +315,6 @@ num_classes: CARD8 use: {IsXKeyboard, IsXPointer, IsXExtensionPointer, IsXExtensionKeyboard, IsExtensionDevice} - attached: CARD8 info: LISTofINPUTINFO name: STRING8] @@ -616,29 +416,6 @@ the device is available for use as an extension device.</para> </listitem> </varlistentry> - <varlistentry><term>attached</term> - <listitem> - <para> - If the use field is <constant>IsXExtensionPointer</constant>, - <emphasis>IsXExtensionKeyboard</emphasis>, or - <emphasis>IsXExtensionDevice</emphasis>, the - <emphasis>attached</emphasis> field specifies the device ID of the - master devices this device is attached to. If the - device is floating, the value is <emphasis>Floating</emphasis>. - If the use field is <emphasis>IsXPointer</emphasis>, - the attached field specifies the paired master keyboard that - provides modifier key states for input events. If the use - field is <emphasis>IsXKeyboard</emphasis>, - the attached field specifies the paired master - pointer that provides the pointer coordinates and - button states for input events. - </para> - <para> - For server implementations supporting XI 1.x only, - the attached field is unspecified. - </para> - </listitem> - </varlistentry> <varlistentry><term>name</term> <listitem> <para>The <emphasis>name</emphasis> field contains a pointer to a null-terminated string that @@ -814,8 +591,7 @@ </variablelist> <para>The information in the <emphasis>InputClassInfo</emphasis> reflects the state of this device at the time the request was - processed. If the device is a master device, it may change - classes in the future (see <xref linkend="xi2_event_processing"/>.</para> + processed.</para> <para>Before it exits, the client program should explicitly request that the server close the device. This is done via the <emphasis>CloseDevice</emphasis> request.</para> @@ -824,11 +600,6 @@ with the same information as the first, but otherwise have no effect. A single <emphasis>CloseDevice</emphasis> request will terminate that client's access to the device.</para> - <para>If the client announces support of XI 2.x, any device returned - through by <emphasis>ListInputDevices</emphasis> can be - opened. Otherwise, only floating SDs may be opened by this - client. - </para> <para>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.</para> @@ -2307,521 +2078,6 @@ <para>If the device reports proximity information, a bit in the mode field indicates whether the device is InProximity or OutOfProximity.</para> </sect2> - <sect2 id='querying_a_devices_pointer'> - <title>Querying A Device's Pointer</title> - <para> - Introduced with XI 2.0. - <literallayout> - QueryDevicePointer - window: WINDOW - deviceid: CARD8 - => - root: WINDOW - child: WINDOW - #x00 None - root-x: INT16 - root-y: INT16 - win-x: INT16 - win-y: INT16 - mask: CARD16 - sameScreen: BYTE - </literallayout> - Errors: Device, Window - </para> - <para> - The root window the specified device's pointer is logically on and - the device's pointer coordinates relative to the root's origin are - returned. If same-screen is <emphasis>False</emphasis>, then the - device's pointer is not on the same screen as the argument window, - child is <emphasis>None</emphasis>, and win-x and win-y are zero. - If same-screen is <emphasis>True</emphasis>, then win-x and win-y - are the device's pointer coordinates relative to the argument - window's origin, and child is the child containing the device's - pointer, if any. The current logical state of the modifier keys - and the buttons are also returned. 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. If the device is a - master device, the state of the modifier keys of the keyboard - paired with this master are returned. If the device is an attached - slave device, the state of the modifier keys of the keyboard - paired with the device's master pointer are returned. If the - device is a floating slave device, the logical state of the - modifier keys is always zero. - </para> - <para>The above description is a modified version of the - <emphasis>QueryPointer</emphasis> request description of the core - protocol. - </para> - </sect2> - <sect2 id='warping_a_devices_pointer'> - <title>Warping A Device's Pointer</title> - <para> - Introduced with XI 2.0. - <literallayout> - WarpDevicePointer - src-window: WINDOW - dst-window: WINDOW - src-x: INT16 - src-y: INT16 - src-width: INT16 - src-height: INT16 - dst-x: INT16 - dst-y: INT16 - deviceid: CARD8 - </literallayout> - Errors: Device, Window, Value - </para> - <para> - If dst-window is <emphasis>None</emphasis>, this request moves the - specified device's pointer by offsets [dst-x, dst-y] relative to - the current position of the device's pointer. If dst-window is a - window, this request moves the device's pointer to [dst-x, dst-y] - relative to dst-window's origin. However, if src-window is not - <emphasis>None</emphasis>, the move only takes place if src-window - contains the device's pointer and the device's pointer is - contained in the specified rectangle of src-window. - - The src-x and src-y coordinates are relative to the src-window's - origin. If src-height is zero, it is replaced with the current - height of src-window minus src-y. If src-width is zero, it is - replaced with the current width of src-window minus src-x. - - This request cannot be used to move the device's pointer outside - the confine-to window of an active pointer grab or device grab. An - attempt will only move the device's pointer as far as the closest - edge of the confine-to window. - - This request will generate an event just as if the user had - instantaneously moved the device's pointer. - - The above description is a modified version of the - <emphasis>WarpPointer</emphasis> request description of the core - protocol. - </para> - </sect2> - <sect2 id='changing_a_devices_cursor'> - <title>Changing A Device's Cursor</title> - <para> - Introduced with XI 2.0. - <literallayout> - ChangeDeviceCursor: - win: WINDOW - cursor: CURSOR - #x00: None - deviceid: CARD8 - </literallayout> - Errors: Device, Window, Cursor - </para> - <para> - If the device's pointer is in the window, the cursor specified - will be used. If a cursor has been set previously for this device - on this window, this request overwrites the previous setting. If - the cursor is <emphasis>None</emphasis>}, the device-specific - cursor shape is removed. The cursor shape selection is as follows: - <itemizedlist> - <listitem><para>Display the device's cursor if a device cursor - has been specified by an earlier - <emphasis>ChangeDeviceCursor</emphasis> request.</para> - </listitem> - <listitem><para>Display the window's cursor if a cursor has - been specified by an earlier - <emphasis>ChangeWindowAttributes</emphasis> - request.</para> - </listitem> - <listitem><para>Repeat on parent window until a cursor shape - has been found.</para> - </listitem> - </itemizedlist> - </para> - </sect2> - <sect2 id='changing_the_device_hierarchy'> - <title>Changing The Device Hierarchy</title> - <para> - Introduced with XI 2.0. - <literallayout> - ChangeDeviceHierarchy - num-changes: CARD8 - changes: ListOfHierarchyChange - </literallayout> - where - <literallayout> - HIERARCHYCHANGE: {CreateMasterInfo, RemoveMasterInfo, - ChangeAttachementInfo} - - CreateMasterInfo: - [class: CARD16 - length: CARD16 - namelen: CARD16 - sendCore: BOOL - enable: BOOL - name: STRING] - - RemoveMasterInfo: - [class: CARD16 - length: CARD16 - deviceid: CARD8 - returnMode: CARD8 - #x01: AttachToMaster - #x02: Floating - returnPointer: CARD8 - returnKeyboard: CARD8] - - ChangeAttachmentInfo: - [class: CARD16 - length: CARD16 - deviceid: CARD8 - changeMode: CARD8 - #x01: AttachToMaster - #x02: Floating - newMaster: CARD8] - </literallayout> - Errors: Device, Value - </para> - <para> - The device hierarchy is modified as specified in changes. Changes - is a list of one or more of <emphasis>CreateMasterInfo</emphasis>, - <emphasis>RemoveMasterInfo</emphasis>, and - <emphasis>ChangeAttachmentInfo</emphasis>. - </para> - <para> - <emphasis>CreateMasterInfo</emphasis> creates a pair of master - devices with the given name. The master pointer's name is - automatically appended with "<space>pointer", the - master keyboard's name is automatically appended with - "<space>keyboard". If sendCore is - <emphasis>True</emphasis>, the new master device sends core - events. If enable is <emphasis>True</emphasis> the new master - device is enabled after creation. Otherwise, the device is - disabled and cannot send events until enabled. </para> - <para> - <emphasis>RemoveMasterInfo</emphasis> removes a pair of master - devices. The deviceid specifies the master device to remove and - the device paired with this master device will be removed - automatically. If returnMode is - <emphasis>AttachToMaster</emphasis>, pointer devices attached to - the master pointer will be attached to the device specified in - returnPointer and keyboard devices attached to the master keyboard - will be attached to the device specified in returnKeyboard. If - returnMode is <emphasis>Floating</emphasis>, - any device attached to the master pointer or master keyboard will - be set floating and values specified in returnPointer and - returnKeyboard are ignored. - </para> - <para> - <emphasis>ChangeAttachmentInfo</emphasis> changes the attachment - of the specified slave device. If changeMode is - <emphasis>AttachToMaster</emphasis>, the device is reattached to - the master device specified in newMaster. If changeMode is - <emphasis>Floating</emphasis>, the device is set to floating and - the value specified in newMaster is ignored. </para> - <para> The changes are processed in order and take effect immediately. - If an error occurs, processing stops and the error is sent to the - client. Changes already processed are not reversed if an error - occurs and the client is required to issue a - <emphasis>ListInputDevices</emphasis> request to obtain the new - device hierarchy. - </para> - <para> - A <emphasis>ChangeDeviceHierarchy</emphasis> request causes a - <emphasis>DeviceHierarchyChanged</emphasis> event to be sent to - all clients. The event is sent if at least one hierarchy change - was successful and is sent even if a subsequent change generates - an error. - </para> - </sect2> - <sect2 id='changing_a_windows_access_permissions'> - <title>Changing A Window's Access Permissions</title> - <para> - Introduced with XI 2.0. - <literallayout> - ChangeWindowAccess - window: WINDOW - npermit:CARD8 - ndeny: CARD8 - defaultRule: CARD8 - #x00: WindowAccessNoRule - #x01: WindowAccessKeepRule - #x02: WindowAccessDenyAll - #x03: WindowAccessAllowAll - clear: CARD8 - #x00: WindowAccessClearNone - #x01: WindowAccessClearPerm - #x02: WindowAccessClearDeny - #x03: WindowAccessClearRule - #x04: WindowAccessClearAll - perm: LISTofCARD8 - deny: LISTofCARD8 - </literallayout> - Errors: Window, Device, Value - </para> - <para> - The access control list of the window is modified. If npermit is - non-zero, the first p bytes after the request specify the device - IDs of the devices permitted to access this window. If ndeny is - non-zero, the first d bytes after the list of permitted devices - specify the device IDs of the devices denied access to this - window. </para> - <para> - If defaultRule is <emphasis>WindowAccessNoRule</emphasis>, the - window does not have a default rule and devices are allowed to - access the window unless a parent window denies access. If - defaultRule is <emphasis>WindowAccessKeepRule</emphasis>, the - window's default rule remains unchanged from the current setting. - If defaultRule is <emphasis>WindowAccessDenyAll</emphasis>, all - devices are denied access to the window. If defaultRule is - <emphasis>WindowAccessAllowAll</emphasis>, all devices are - permitted access to the window even if a parent window restricts - access. </para> - <para> - If clear is not <emphasis>WindowAccessClearNone</emphasis>, a - binary mask specifies the acces permissions to remove. If - <emphasis>WindowAccessClearPerm</emphasis> is set, the list of - permitted devices is freed. If - <emphasis>WindowAccessClearDeny</emphasis> is set, the list of - denied devices is freed. If - <emphasis>WindowAccessClearRule</emphasis> is set, the default - rule is set to <emphasis>WindowAccessNoRule</emphasis>. If clear - is <emphasis>WindowAccessClearAll</emphasis>, all of the window's - access settings are reset. </para> - <para> - The X server tests each event for access control in the following - order: - <itemizedlist> - <listitem><para> If the given device is in the perm list of - the current window, send the event.</para></listitem> - <listitem><para> If the defaultRule of the current window is - <emphasis>WindowAccessDenyAll</emphasis>, discard the - event.</para></listitem> - <listitem><para> If the given device is in the deny list of - the current window, discard the - event.</para></listitem> <listitem><para> If the - defaultRule of the current window is - <emphasis>WindowAccessAllowAll</emphasis>, send the - event.</para></listitem> - <listitem><para> If window has a parent window, repeat on - parent window. Otherwise, send the - event.</para></listitem> </itemizedlist> - This process is repeated until a rule of a window explicitly - states that the event may be sent or that the event must be - discarded. - </para> - </sect2> - <sect2 id="querying_a_windows_access_permissions"> - <title>Querying A Window's Access Permissions</title> - <para> - Introduced with XI 2.0. - <literallayout> - QueryWindowAccess - window: WINDOW - => - defaultRule: CARD8 - #x00: WindowAccessNoRule - #x01: WindowAccessDenyAll - #x02: WindowAccessAllowAll - npermit: CARD8 - ndeny: CARD8 - perm: LISTofCARD8 - deny: LISTofCARD8 - </literallayout> - Errors: Window - </para> - <para> - The device access control settings of the specified window are - returned. If npermit is non-zero, the first p bytes after the - request specify the device IDs of the devices explicitly - permitted access to the window. If ndeny is non-zero, the first d - bytes after the list of permitted devices specify the device IDs - of the devices denied access to the window. - </para> - <para> - The defaultRule can be <emphasis>WindowAccessNoRule</emphasis>, - <emphasis>WindowAccessDenyAll</emphasis> or - <emphasis>WindowAccessAllowAll</emphasis>. - </para> - </sect2> - <sect2 id="setting_the_client_pointer"> - <title>Setting The ClientPointer</title> - <para> - Introduced with XI 2.0 - <literallayout> - SetClientPointer - window: WINDOW - deviceid: CARD8 - </literallayout> - Errors: Window, Device - </para> - <para> - The ClientPointer of the client specified by window is set to the - device specified by deviceid. Window may be a client ID instead of - a window ID. - </para> - </sect2> - <sect2 id="querying_the_client_pointer"> - <title>Querying The ClientPointer</title> - <para> - Introduced with XI 2.0l. - <literallayout> - GetClientPointer - window: WINDOW - </literallayout> - Errors: Window - </para> - <para> - The ClientPointer setting for the client specified by window is - returned. If set is <emphasis>True</emphasis>, deviceid specifies - the device set as ClientPointer. Otherwise, the client does not - have a ClientPointer set and deviceid is undefined. Window may be - client ID instead of a window ID. - </para> - </sect2> - <sect2 id="registering_for_generic_events"> - <title>Registering For XI-specific GenericEvents</title> - <para> - Introduced with XI 2.0 - <literallayout> - XiSelectEvent - window: WINDOW - mask: CARD32 - deviceid: CARD8 - #0x1f: AllDevices - </literallayout> - Errors: Window, Device, Value - </para> - <para> - Register for the GenericEvents specified in mask on window for the - device specified with deviceid. This request will overwrite a - previous setting for the same device on the same window. If - deviceid is <emphasis>AllDevices</emphasis>, the event mask - applies to all devices. A device mask for - <emphasis>AllDevices</emphasis> is stored separately from the - device masks and has precedence over a device mask. - </para> - </sect2> - <sect2 id="issuing_an_extended_device_grab"> - <title>Issuing An Extended Device Grab</title> - <para> - Introduced with XI 2.0 - <literallayout> - ExtendedGrabDevice - grab-window: Window - time: TIMESTAMP - #0x00: CurrentTime - deviceid: CARD8 - device-mode: CARD8 - #0x00: GrabModeSync - #0x01: GrabModeAsync - owner-events: BOOL - confine-to: WINDOW - cursor: CURSOR - event-count: CARD16 - generic-event-count: CARD16 - event-list: LISTofEVENTCLASS - generic-event-list: LISTofGENERICEVENTCLASS - => - status: CARD8 - </literallayout> - where - <literallayout> - GENERICEVENTCLASS: - extension: CARD8 - evmask: CARD32 - </literallayout> - Errors: Window, Device, Value - </para> - <para> - 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. - </para> - <para> - 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. - </para> - <para> - The generic-event-list parameter is a pointer to a list of generic - event classes. These are used to indicate which generic events the - client wishes to receive while the device is grabbed. - </para> - <para> - If owner-events is <emphasis>False</emphasis>, 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 or generic-event-list. If owner-events is - <emphasis>True</emphasis>, 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 of the generic-event-list. For either value of - owner-events, unreported events are discarded. - </para> - <para> - If device-mode is <emphasis>GrabModeAsync</emphasis>, device event - processing continues normally. If the device is currently frozen - by this client, then processing of device events is resumed. If - device-mode is <emphasis>GrabModeSync</emphasis>, 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 - <emphasis>AllowDeviceEvents</emphasis> 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. - </para> - <para> - If a cursor is specified and the device is a master pointer, then - it is displayed regardless of what window the device's pointer is - in. If no cursor is specified, then when the pointer is in - grab-window or one of its subwindows, the normal cursor for that - window is displayed. Otherwise, the cursor for grab-window is - displayed. - </para> - <para> - If a confine-to window is specified and the device is a master - pointer, then the pointer will be restricted to stay contained in - that window. The confine-to window need have no relationship to - the grab-window. If the pointer is not initially in the confine-to - window, then it is warped automatically to the closest edge (and - enter/leave events are generated normally) just before the grab - activates. If the confine-to window is subsequently reconfigured, - the pointer is warped automatically, as necessary, to keep it - contained in the window. - </para> - <para> - This request generates <emphasis>DeviceFocusIn</emphasis> and - <emphasis>DeviceFocusOut</emphasis> events for keyboard devices - and <emphasis>DeviceEnterNotify</emphasis> and - <emphasis>DeviceLeaveNotify</emphasis> for pointer devices. - </para> - <para> - This request fails and returns: - <itemizedlist> - <listitem> - <para> <emphasis>AlreadyGrabbed,</emphasis> if the device - is actively grabbed by some other - client.</para></listitem> - <listitem><para> <emphasis>NotViewable,</emphasis> if - grab-window is not viewable. </para></listitem> - <listitem><para> <emphasis>InvalidTime,</emphasis> if the - specified time is earlier than the last-grab-time for - the specified device or later than the current X - server time. Otherwise, the last-grab-time for the - specified device is set to the specified time and - <emphasis>CurrentTime</emphasis> is replaced by the - current X server time. </para></listitem> - <listitem><para> <emphasis>Frozen,</emphasis> if the device is - frozen by an active grab of another - client.</para></listitem> - </itemizedlist> - </para> - <para> - The above description is a modified version of the - <emphasis>GrabDevice</emphasis> request description, and the - <emphasis>GrabPointer</emphasis> request description from the core - protocol. - </para> - </sect2> <sect2 id="listing_a_devices_properties"> <title>Listing Device Properties</title> <para> @@ -3015,25 +2271,11 @@ Otherwise, it is set to None. </para> <para> - XI 1.x: 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. </para> <para> - XI 2.x: - The state component gives the logical state of the buttons - or keys on the device specified in the event field. If the - device is a master device, the state component also contains - the modifier keys on the paired master device. If the device - is a slave device, the state component also contains the - modifier keys or buttons of the master device paired with this - device's master device. If the device is not attached to a - master device, the state component only contains the logical - state of the buttons or keys of this device, with all other - bits set to zero. - </para> - <para> The detail component type varies with the event type: <informaltable pgwide='0' frame='all'> <tgroup cols='2' align='center' colsep='1' rowsep='1'> @@ -3310,157 +2552,6 @@ that has been changed. </para> </sect2> - <sect2 id='device_crossing_events'> - <title>DeviceCrossingEvents</title> - <para> - Introduced with XI 2.0. - <literallayout> - DeviceEnterEvent - DeviceLeaveEvent - detail: BYTE - #0x00: Ancestor - #0x01: Virtual - #0x02: Inferior - #0x03: Nonlinear - #0x04: NonlinearVirtual - time: TIMESTAMP - root: WINDOW - event: WINDOW - child: WINDOW - #0x00: None - root-x: INT16 - root-y: INT16 - event-x: INT16 - event-y: INT16 - state: SETofKEYBUTMASK - mode: BYTE - #x00: Normal - #x01: Grab - #x10: SameScreen - #x20: Focus - deviceid: CARD8 - </literallayout> - </para> - <para> - If pointer motion or a window hierarchy change causes the - device's pointer to be in a different window than before, - <emphasis>DeviceEnterNotify</emphasis> and - <emphasis>DeviceLeaveNotify</emphasis> events are generated - instead of a <emphasis>DeviceMotionNotify</emphasis> event. - The deviceid specifies the device that generated the - <emphasis>DeviceEnterNotify</emphasis> or - <emphasis>DeviceLeaveNotify</emphasis> event. </para> - <para> - Only clients selecting DeviceEnter on a window receive - <emphasis>DeviceEnterNotify</emphasis> ev\-ents, and only - clients selecting DeviceLeave receive - <emphasis>DeviceLeaveNotify</emphasis> events. The device's - pointer position reported in the event is always the final - position, not the initial position of the device's pointer. - The root is the root window for this position, and root-x and - root-y are the device's 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 device's pointer coordinates relative to - the event window's origin and mode has the - <emphasis>SameScreen</emphasis> bit set. Otherwise, event-x - and event-y are zero and the <emphasis>SameScreen</emphasis> - bit is unset. In a <emphasis>DeviceLeaveNotify</emphasis> - event, if a child of the event window contains the initial - position of the device's pointer, then the child component is - set to that child. Otherwise, it is <emphasis>None</emphasis>. - For a <emphasis>DeviceEnterNotify</emphasis> event, if a child - of the event window contains the final pointer position, then - the child component is set to that child. Otherwise, it is - <emphasis>None</emphasis>. If the event window is the focus - window or an inferior of the focus window, then mode has the - <emphasis>Focus</emphasis> bit set. Otherwise, the - <emphasis>Focus</emphasis> bit is unset. - </para> - <para> - Normal pointer motion events have mode - <emphasis>Normal</emphasis>. Pseudo-motion events when a grab - activates have mode <emphasis>Grab</emphasis>, and - pseudo-motion events when a grab deactivates have mode - <emphasis>Ungrab</emphasis>. Only the lower four bits must be - considered when determining the grab mode. </para> - <para> - All <emphasis>DeviceEnterNotify</emphasis> and - <emphasis>DeviceLeaveNotify</emphasis> events caused by a - window hierarchy change are generated after any hierarchy - event caused by that change (that is - <emphasis>UnmapNotify</emphasis>, - <emphasis>MapNotify</emphasis>, - <emphasis>ConfigureNotify</emphasis>, - <emphasis>GravityNotify</emphasis>, - <emphasis>CirculateNotify</emphasis>), but the ordering of - <emphasis>DeviceEnterNotify</emphasis> and - <emphasis>DeviceLeaveNotify</emphasis> events with respect to - <emphasis>DeviceFocusOut</emphasis> events is not constrained. - </para> - <para> - The above description is a modified version of the - <emphasis>EnterNotify</emphasis> and - <emphasis>LeaveNotify</emphasis> event description from - the core protocol. For a detailed description about the - generation of <emphasis>EnterNotify</emphasis> and - <emphasis>LeaveNotify</emphasis> events see - the core protocol specification. - </para> - </sect2> - <sect2 id='device_hierarchy_changed_event'> - <title>Device Hierarchy Changed Event</title> - <para> - Introduced with XI 2.0. - <literallayout> - DeviceHierarchyChangedEvent - time: TIMESTAMP - </literallayout> - The DeviceHierarchyChangedEvent is a GenericEvent. - </para> - <para> - If a client modifies the device hierarchy through the - <emphasis>ChangeDeviceHierarchy</emphasis> request, a - <emphasis>DeviceHierarchyChangedEvent</emphasis> is sent to - all clients. The event does not include information about the - device hierarchy and a client is expected to issue a - <emphasis>ListInputDevices</emphasis> request to obtain the - new device hierarchy. - </para> - </sect2> - - <sect2 id='device_classes_changed_event'> - <title>DeviceClassesChangedEvent</title> - <para> - Introduced with XI 2.0. - <literallayout> - DeviceClassesChangedEvent - deviceid: CARD8 - new-slave: CARD8 - time: TIMESTAMP - num-classes: CARD8 - classes: LISTofINPUTINFO - </literallayout> - The DeviceClassesChangedEvent is a GenericEvent. - </para> - <para> - A <emphasis>DeviceClassesChangedEvent</emphasis> is sent to - all clients when an event from a slave device causes a master - device to change its classes. - </para> - <para> - The deviceid specifies the master device that has changed - state and new-slave is set to the device ID of the slave - device that now sends events through this master device. The - event is followed by num-classes elements of - <emphasis>KeyInfo</emphasis>, - <emphasis>ValuatorInfo</emphasis>, and - <emphasis>ButtonInfo</emphasis> that reflect the capabilities - of the slave device. For a description of - <emphasis>INPUTINFO</emphasis>, see - <xref linkend="listing_available_devices"/>. - </para> - </sect2> <sect2 id='device_property_notify_event'> <title>DevicePropertyNotifyEvent</title> <para> |