diff options
| author | Peter Hutterer <peter@cs.unisa.edu.au> | 2008-05-10 23:22:25 +0930 |
|---|---|---|
| committer | Peter Hutterer <peter@cs.unisa.edu.au> | 2008-05-11 23:22:14 +0930 |
| commit | 8d70d2e02231a535299ab48e88928d6c853bc71a (patch) | |
| tree | a64c801fa3ed63435d628e67bb83cecba64fe37e | |
| parent | 3122c88092b11253ed8ee43d70d692fa5428fbce (diff) | |
Xi specs: clean up xml, try to get a readable output.
doclifter isn't perfect.
| -rw-r--r-- | specs/Xi/protocol.xml | 5143 |
1 files changed, 2296 insertions, 2847 deletions
diff --git a/specs/Xi/protocol.xml b/specs/Xi/protocol.xml index 88e3be5..fc2cba5 100644 --- a/specs/Xi/protocol.xml +++ b/specs/Xi/protocol.xml @@ -1,2851 +1,2300 @@ <?xml version="1.0" encoding="ISO-8859-1"?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> -<!-- lifted from troff+ms by doclifter --> +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"> +<!-- lifted from troff+ms by doclifter + Hand-corrected by Peter Hutterer --> <article id='protocolms'> -<sect1 id="input_extension"><title>Input Extension</title> -<para> - <literallayout> - X11 Input Extension Protocol Specification - Version 1.0 - X Consortium Standard - X Version 11, Release 6.8 - Mark Patrick, Ardent Computer - George Sachs, Hewlett-Packard - </literallayout> -</para> -<para>Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and Ardent - Computer</para> -<para>Permission to use, copy, modify, and distribute this documentation for -any purpose and without fee is hereby granted, provided that the above -copyright notice and this permission notice appear in all copies. -Ardent and Hewlett-Packard make no representations about the suitability -for any purpose of the information in this document. It is provided "as is" -without express or implied warranty. -Copyright © 1989, 1990, 1991, 1992 X Consortium</para> -<para>Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the “Software”), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions:</para> -<para>The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software.</para> -<para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN -AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN -CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para> -<para>Except as contained in this notice, the name of the X Consortium shall not be -used in advertising or otherwise to promote the sale, use or other dealings -in this Software without prior written authorization from the X Consortium. -<emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.</para> -<!-- .ps --> -<!-- .vs --> -<!-- .bp 1 --> -<!-- .EH '\fBX Input Extension Protocol Specification\fP''\fBX11, Release 6.8\fP' --> -<!-- .OH '\fBX Input Extension Protocol Specification\fP''\fBX11, Release 6.8\fP' --> -<!-- .EF ''\fB\\n(PN\fP'' --> -<!-- .OF ''\fB\\n(PN\fP'' --> -<!-- Force the heading counter for level 1 to one --> -<!-- Print table of contents to level 4 headings --> -<!-- Page eject for each level 1 heading --> -<!-- Define Ch to contain the chapter string. --> -<!-- Pull in the layout macro package. --> -<sect2><title>Input Extension Overview</title> -<para>This document defines an extension to the X11 protocol to support -input devices other than the core X keyboard and pointer. -An accompanying document defines a corresponding extension to Xlib -(similar extensions for languages other than C are anticipated). -This first section gives an overview of the input extension. The -next section defines the new protocol requests defined by the extension. -We conclude with a description of the new input events generated by -the additional input devices.</para> -</sect2> -<sect2 id='design_approach'><title>Design Approach</title> -<para>The design approach of the extension is to define requests -and events analogous to the core requests and events. This allows -extension input devices to be individually distinguishable from each other -and from the core input devices. These requests and events make use -of a device identifier and support the reporting of n-dimensional motion -data as well as other data that is not reportable via the core -input events.</para> -</sect2> -<sect2 id='core_input_devices'><title>Core Input Devices</title> -<para>The X server core protocol supports two input devices: a pointer and a -keyboard. The pointer device has two major functions. -First, it may be used to generate motion information -that client programs can detect. Second, it may also be used to indicate the -current location and focus of the X keyboard. To accomplish this, the server -echoes a cursor at the current position of the X pointer. Unless the X -keyboard has been explicitly focused, this cursor also shows the current -location and focus of the X keyboard.</para> -<para>The X keyboard is used to generate input that client programs can detect.</para> -<para>The X keyboard and X pointer are referred to in this document as -the <emphasis remap='I'>core devices</emphasis>, and the input -events they generate (<emphasis remap='B'>KeyPress</emphasis>, <emphasis remap='B'>KeyRelease</emphasis>, <emphasis remap='B'>ButtonPress</emphasis>, -<emphasis remap='B'>ButtonRelease</emphasis>, and -<emphasis remap='B'>MotionNotify</emphasis>) are known as the <emphasis remap='I'>core input events</emphasis>. All other -input devices are referred to as <emphasis remap='I'>extension input devices</emphasis> and the -input events they generate are referred to as <emphasis remap='I'>extension input events</emphasis>.</para> -<para>This input extension does not change the behavior or functionality of the -core input devices, core events, or core protocol requests, with the -exception of the core grab requests. These requests may affect the -synchronization of events from extension devices. See the explanation -in the section titled "Event Synchronization and Core Grabs".</para> -<para>Selection of the physical devices to be initially used by the server as the -core devices is left implementation-dependent. Requests are defined that -allow client programs to change which physical devices are used as the -core devices.</para> -</sect2> -<sect2 id='extension_input_devices'><title>Extension Input Devices</title> -<para>The input extension 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.</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 -<emphasis remap='B'>ListInputDevices</emphasis> request, which will return a list of all devices that -can be opened by the X server. A client can then open one or more of these -devices using the <emphasis remap='B'>OpenDevice</emphasis> request, specify what events they are -interested in receiving, and receive and process input events from extension -devices in the same way as events from the X keyboard and X pointer. -Input events from these devices are of extension types (<emphasis remap='B'>DeviceKeyPress</emphasis>, -<emphasis remap='B'>DeviceKeyRelease</emphasis>, <emphasis remap='B'>DeviceButtonPress</emphasis>, <emphasis remap='B'>DeviceButtonRelease</emphasis>, -<emphasis remap='B'>DeviceMotionNotify</emphasis>, etc.) and contain a device identifier so that events -of the same type coming from different input devices can be distinguished.</para> -<para>Any kind of input device may be used as an extension input device. -Extension input devices may have 0 or more keys, 0 or more buttons, -and may report 0 or more axes of motion. Motion may be reported -as relative movements from a previous position or as an absolute -position. All valuators reporting motion information for a given -extension input device must report the same kind of motion information -(absolute or relative).</para> -<para>This extension is designed to accommodate new types of input devices that -may be added in the future. The protocol requests that refer to -specific characteristics of input devices organize that information -by <emphasis remap='B'>input classes</emphasis>. Server implementors may add new -classes of input devices without changing the protocol requests. -Input classes are unique numbers registered with the X Consortium. -Each extension input device may support multiple input classes.</para> -<para>All extension input devices are treated like the core X keyboard in -determining their location and focus. The server does not track the -location of these devices on an individual basis, and therefore -does not echo a cursor to indicate their current location. -Instead, their location is determined by the location of the core X pointer. -Like the core X keyboard, some may be explicitly focused. If they are -not explicitly focused, their focus is determined by the location of the -core X pointer.</para> -<para>Input events reported by the server to a client are of fixed size (32 bytes). -In order to represent the change in state of an input device the extension -may need to generate a sequence of input events. A client side library -(such as Xlib) will typically take these raw input events and format -them into a form more convenient to the client.</para> -<sect3 id='event_classes'><title>Event Classes</title> -<para>In the core protocol a client registers interest in receiving certain -input events directed to a window by modifying that window's event-mask. -Most of the bits in the event mask are already used to specify interest -in core X events. The input extension specifies a different mechanism by which -a client can express interest in events generated by this extension.</para> -<para>When a client opens a extension input device via the <emphasis remap='B'>OpenDevice</emphasis> request, -an <emphasis remap='B'>XDevice</emphasis> structure is returned. Macros are provided that extract -32-bit numbers called <emphasis remap='B'>event classes</emphasis> from that structure, that a client -can use to register interest in extension events via the -<emphasis remap='B'>SelectExtensionEvent</emphasis> request. The event class combines the desired -event type and device id, and may be thought of as the equivalent of core -event masks.</para> -</sect3> -<sect3 id='input_classes'><title>Input Classes</title> -<para>Some of the input extension requests divide input devices into classes -based on their functionality. This is intended to allow new classes of input -devices to be defined at a later time without changing the semantics of -these requests. The following input device classes are currently -defined:</para> -<!-- .RS --> -<!-- .in +5n --> -<variablelist remap='IP'> - <varlistentry> - <term><emphasis remap='B'>KEY</emphasis></term> - <listitem> -<para>The device reports key events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>BUTTON</emphasis></term> - <listitem> -<para>The device reports button events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>VALUATOR</emphasis></term> - <listitem> -<para>The device reports valuator data in motion events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>PROXIMITY</emphasis></term> - <listitem> -<para>The device reports proximity events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>FOCUS</emphasis></term> - <listitem> -<para>The device can be focused and reports focus events.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>FEEDBACK</emphasis></term> - <listitem> -<para>The device supports feedbacks.</para> - </listitem> - </varlistentry> - <varlistentry> - <term><emphasis remap='B'>OTHER</emphasis></term> - <listitem> -<para>The <emphasis remap='B'>ChangeDeviceNotify</emphasis>, <emphasis remap='B'>DeviceMappingNotify</emphasis>, and -<emphasis remap='B'>DeviceStateNotify</emphasis> macros may be invoked passing the <emphasis remap='B'>XDevice</emphasis> -structure returned for this device.</para> -<!-- .in \-5n --> -<!-- .RE --> -<para>Each extension input device may support multiple input classes. -Additional classes may be added in the future. -Requests that support multiple input classes, such as the -<emphasis remap='B'>ListInputDevices</emphasis> function that lists all available input devices, -organize the data they return by input class. Client programs that -use these requests should not access data unless it matches a -class defined at the time those clients were compiled. In this way, -new classes can be added without forcing existing clients that use -these requests to be recompiled.</para> - </listitem> - </varlistentry> -</variablelist> -</sect3> -</sect2> -</sect1> -<sect1 id='requests'><title>Requests</title> -<para>Extension input devices are accessed by client programs through the -use of new protocol requests. This section summarizes the new requests -defined by this extension. The syntax and type definitions used below -follow the notation used for the X11 core protocol.</para> -<sect2 id='getting_the_extension_version'><title>Getting the Extension Version</title> -<para>The <emphasis remap='B'>GetExtensionVersion</emphasis> request returns version information about -the input extension. -GetExtensionVersion -<!-- .in +.5i --> -name: STRING -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -<!-- .br --> -present: BOOL -<!-- .br --> -protocol-major-version: CARD16 -<!-- .br --> -protocol-minor-version: CARD16 -<!-- .br --> -The protocol version numbers returned indicate the version of the input -extension supported by the target X server. The version numbers can be -compared to constants defined in the header file <filename>XI.h</filename>. Each version is -a superset of the previous versions.</para> -</sect2> -<sect2 id='listing_available_devices'><title>Listing Available Devices</title> -<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 -<emphasis remap='B'>ListInputDevices</emphasis> request, which will return a list of all devices that -can be opened by the X server. -ListInputDevices -<!-- .br --> -=> -<!-- .in +.5i --> -<!-- .br --> -input-devices: LISTofDEVICEINFO -<!-- .br --> -<!-- .in \-.5i --> -where</para> -<!-- .in +.5i --> -<!-- .br --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DEVICEINFO:</entry> - <entry align='left'><para>[type: ATOM -<!-- .br --> - id: CARD8 -<!-- .br --> - num_classes: CARD8 -<!-- .br --> - use: {IsXKeyboard, IsXPointer, IsExtensionDevice} -<!-- .br --> - info: LISTofINPUTINFO -<!-- .br --> - name: STRING8]</para></entry> - </row> - <row> - <entry align='left'>INPUTINFO:</entry> - <entry align='left'>{KEYINFO, BUTTONINFO, VALUATORINFO}</entry> - </row> - <row> - <entry align='left'>KEYINFO:</entry> - <entry align='left'>[class: CARD8 -<!-- .br --> - length: CARD8 -<!-- .br --> - min-keycode: KEYCODE -<!-- .br --> - max-keycode: KEYCODE -<!-- .br --> - num-keys: CARD16]</entry> - </row> - <row> - <entry align='left'>BUTTONINFO:</entry> - <entry align='left'><!-- .br --> -[class: CARD8 -<!-- .br --> - length: CARD8 -<!-- .br --> - num-buttons: CARD16]</entry> - </row> - <row> - <entry align='left'>VALUATORINFO:</entry> - <entry align='left'>[class: CARD8 -<!-- .br --> - length: CARD8 -<!-- .br --> - num_axes: CARD8 -<!-- .br --> - mode: SETofDEVICEMODE -<!-- .br --> - motion_buffer_size: CARD32 -<!-- .br --> - axes: LISTofAXISINFO]</entry> - </row> - <row> - <entry align='left'>AXISINFO:</entry> - <entry align='left'>[resolution: CARD32 -<!-- .br --> - min-val: CARD32 -<!-- .br --> - max-val: CARD32]</entry> - </row> - <row> - <entry align='left'>DEVICEMODE:</entry> - <entry align='left'>{Absolute, Relative}</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .br --> -<para>Errors: None</para> -<!-- .in \-.5i --> -<para> -This request returns a list of all devices that can be opened by the X -server, -including the core X keyboard and X pointer. Some implementations may open -all input devices as part of X initialization, while others may not open -an input device until requested to do so by a client program.</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>The information returned for each device is as follows:</para> -<para>The <emphasis remap='B'>type</emphasis> field is of type <emphasis remap='B'>Atom</emphasis> and indicates the nature of the -device. Clients may determine device types by invoking the <emphasis remap='B'>XInternAtom</emphasis> -request passing one of the names defined in the header file <filename>XI.h</filename>. The -following names have been defined to date:</para> -<literallayout remap='DS'> -<emphasis remap='B'>MOUSE</emphasis> -<emphasis remap='B'>TABLET</emphasis> -<emphasis remap='B'>KEYBOARD</emphasis> -<emphasis remap='B'>TOUCHSCREEN</emphasis> -<emphasis remap='B'>TOUCHPAD</emphasis> -<emphasis remap='B'>BUTTONBOX</emphasis> -<emphasis remap='B'>BARCODE</emphasis> -<emphasis remap='B'>KNOB_BOX</emphasis> -<emphasis remap='B'>TRACKBALL</emphasis> -<emphasis remap='B'>QUADRATURE</emphasis> -<emphasis remap='B'>SPACEBALL</emphasis> -<emphasis remap='B'>DATAGLOVE</emphasis> -<emphasis remap='B'>EYETRACKER</emphasis> -<emphasis remap='B'>CURSORKEYS</emphasis> -<emphasis remap='B'>FOOTMOUSE</emphasis> -<emphasis remap='B'>ID_MODULE</emphasis> -<emphasis remap='B'>ONE_KNOB</emphasis> -<emphasis remap='B'>NINE_KNOB</emphasis> -</literallayout> <!-- remap='DE' --> -<para>The <emphasis remap='B'>id</emphasis> is a small cardinal value in the range 0-128 that uniquely -identifies the device. It is assigned to the device when it is initialized by -the server. Some implementations may not open an input device until requested -by a client program, and may close the device when the last client accessing -it requests that it be closed. -If a device is opened by a client program via <emphasis remap='B'>XOpenDevice</emphasis>, -then closed via <emphasis remap='B'>XCloseDevice</emphasis>, then opened again, it is not guaranteed -to have the same id after the second open request.</para> -<para>The <emphasis remap='B'>num_classes</emphasis> field is a small cardinal value in the range 0-255 -that specifies the number of input classes supported by the device for -which information is returned by <emphasis remap='B'>ListInputDevices</emphasis>. Some input classes, -such as class <emphasis remap='B'>Focus</emphasis> and class <emphasis remap='B'>Proximity</emphasis> do not have any information -to be returned by <emphasis remap='B'>ListInputDevices</emphasis>.</para> -<para>The <emphasis remap='B'>use</emphasis> field specifies how the device is currently being used. If the -value is <emphasis remap='B'>IsXKeyboard</emphasis>, the device is currently being used as the -X keyboard. If the value is <emphasis remap='B'>IsXPointer</emphasis>, the device is currently -being used as the X pointer. If the value is <emphasis remap='B'>IsXExtensionDevice</emphasis>, -the device is available for use as an extension device.</para> -<para>The <emphasis remap='B'>name</emphasis> field contains a pointer to a null-terminated string that -corresponds to one of the defined device types.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para><emphasis remap='B'>InputInfo</emphasis> is one of: <emphasis remap='B'>KeyInfo</emphasis>, <emphasis remap='B'>ButtonInfo</emphasis> or -<emphasis remap='B'>ValuatorInfo</emphasis>. The first two fields are common to all three:</para> -<para>The <emphasis remap='B'>class</emphasis> field is a cardinal value in the range 0-255. It uniquely -identifies the class of input for which information is returned.</para> -<para>The <emphasis remap='B'>length</emphasis> field is a cardinal value in the range 0-255. It specifies -the number of bytes of data that are contained in this input class. The -length includes the class and length fields.</para> -<para>The remaining information returned for input class <emphasis remap='B'>KEYCLASS</emphasis> is as follows:</para> -<para><emphasis remap='B'>min_keycode</emphasis> is of type KEYCODE. It specifies the minimum keycode that -the device will report. The minimum keycode will not be smaller than 8.</para> -<para><emphasis remap='B'>max_keycode</emphasis> is of type KEYCODE. It specifies the maximum keycode that -the device will report. The maximum keycode will not be larger than 255.</para> -<para><emphasis remap='B'>num_keys</emphasis> is a cardinal value that specifies the number of keys that the -device has.</para> -<para>The remaining information returned for input class <emphasis remap='B'>BUTTONCLASS</emphasis> is as -follows:</para> -<para><emphasis remap='B'>num_buttons</emphasis> is a cardinal value that specifies the number of buttons -that the device has.</para> -<para>The remaining information returned for input class <emphasis remap='B'>VALUATORCLASS</emphasis> is as -follows:</para> -<para><emphasis remap='B'>mode</emphasis> is a constant that has one of the following values: <emphasis remap='B'>Absolute</emphasis> -or <emphasis remap='B'>Relative</emphasis>. Some devices allow the mode to be changed dynamically -via the <emphasis remap='B'>SetDeviceMode</emphasis> request.</para> -<para><emphasis remap='B'>motion_buffer_size</emphasis> is a cardinal number that specifies the number of -elements that can be contained in the motion history buffer for the device.</para> -<para>The <emphasis remap='B'>axes</emphasis> field contains a pointer to an AXISINFO struture.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>The information returned for each axis reported by the device is:</para> -<para>The <emphasis remap='B'>resolution</emphasis> is a cardinal value in counts/meter.</para> -<para>The <emphasis remap='B'>min_val</emphasis> field is a cardinal value in that contains the minimum -value the device reports for this axis. For devices whose mode is -<emphasis remap='B'>Relative</emphasis>, the min_val field will contain 0.</para> -<para>The <emphasis remap='B'>max_val</emphasis> field is a cardinal value in that contains the maximum -value the device reports for this axis. For devices whose mode is -<emphasis remap='B'>Relative</emphasis>, the max_val field will contain 0.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='enabling_devices'><title>Enabling Devices</title> -<para>Client programs that wish to access an extension device must request that -the server open that device. This is done via the <emphasis remap='B'>OpenDevice</emphasis> -request. -OpenDevice -<!-- .in +.5i --> -id: CARD8 -<!-- .in \-.5i --> -=></para> -<!-- .in +.5i --> -<!-- .br --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DEVICE:</entry> - <entry align='left'><para>[device_id: XID -<!-- .br --> - num_classes: INT32 -<!-- .br --> - classes: LISTofINPUTCLASSINFO]</para></entry> - </row> - <row> - <entry align='left'>.sp</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>INPUTCLASSINFO:</entry> - <entry align='left'>[input_class: CARD8 -<!-- .br --> - event_type_base: CARD8]</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<para>Errors: Device</para> -<!-- .in \-.5i --> -<para>This request returns the event classes to be used by the client to indicate -which events the client program wishes to receive. Each input class -may report several event classes. For example, input class <emphasis remap='B'>Keys</emphasis> reports -<emphasis remap='B'>DeviceKeyPress</emphasis> and <emphasis remap='B'>DeviceKeyRelease</emphasis> event classes. Input classes -are unique numbers registered with the X Consortium. Input class -<emphasis remap='B'>Other</emphasis> exists -to report event classes that are not specific to any one input class, -such as <emphasis remap='B'>DeviceMappingNotify</emphasis>, <emphasis remap='B'>ChangeDeviceNotify</emphasis>, and -<emphasis remap='B'>DeviceStateNotify</emphasis>.</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>The information returned for each device is as follows:</para> -<para>The <emphasis remap='B'>device_id</emphasis> is a number that uniquely identifies the device.</para> -<para>The <emphasis remap='B'>num_classes</emphasis> field contains the number of input classes supported -by this device.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>For each class of input supported by the device, -the <emphasis remap='B'>InputClassInfo</emphasis> structure contains the following information:</para> -<para>The <emphasis remap='B'>input_class</emphasis> is a small cardinal number that identifies the class -of input.</para> -<para>The <emphasis remap='B'>event_type_base</emphasis> is a small cardinal number that specifies the -event type of one of the events reported by this input class. This information -is not directly used by client programs. Instead, the <emphasis remap='B'>Device</emphasis> is used -by macros that return extension event types and event classes. This is -described in the section of this document entitled "Selecting Extension -Device Events".</para> -<para>Before it exits, -the client program should explicitly request that the server close -the device. This is done via the <emphasis remap='B'>CloseDevice</emphasis> request.</para> -<para>A client may open the same extension device more than once. Requests -after the first successful one return an additional <emphasis remap='B'>XDevice</emphasis> structure -with the same information as the first, but otherwise have no effect. -A single <emphasis remap='B'>CloseDevice</emphasis> request will terminate that client's access to -the device.</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> -<para>If a client program terminates without closing a device, the server will -automatically close that device on behalf of the client. This does not -affect any other clients that may be accessing that device.</para> -<para>CloseDevice -<!-- .in +.5i --> -device: DEVICE -<!-- .br --> -Errors: Device</para> -<!-- .br --> -<!-- .in \-.5i --> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='changing_the_mode_of_a_device'><title>Changing The Mode Of A Device</title> -<para>Some devices are capable of reporting either relative or absolute motion -data. To change the mode of a device from relative to absolute, use the -<emphasis remap='B'>SetDeviceMode</emphasis> request. The valid values are <emphasis remap='B'>Absolute</emphasis> or -<emphasis remap='B'>Relative</emphasis>.</para> -<para>This request will fail and return <emphasis remap='B'>DeviceBusy</emphasis> if another client already -has the device open with a different mode. It will fail and return -<emphasis remap='B'>AlreadyGrabbed</emphasis> if another client has the device grabbed. -The request will fail with -a <emphasis remap='B'>BadMatch</emphasis> error if the requested mode is not supported by the device. -SetDeviceMode -<!-- .in +.5i --> -device: DEVICE -<!-- .br --> -mode: {Absolute, Relative} -<!-- .br --> -Errors: Device, Match, Mode -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -status: {Success, DeviceBusy, AlreadyGrabbed}</para> -<!-- .br --> -<!-- .in \-.5i --> -</sect2> -<sect2 id='initializing_valuators_on_an_input_devic'><title>Initializing Valuators on an Input Device</title> -<para>Some devices that report absolute positional data can be initialized to a -starting value. Devices that are capable of reporting relative motion or -absolute positional data may require that their valuators be initialized -to a starting value after the mode of the device is changed to <emphasis remap='B'>Absolute</emphasis>. -To initialize the valuators on such a device, use the <emphasis remap='B'>SetDeviceValuators</emphasis> -request. -SetDeviceValuators -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -first_valuator: CARD8 -<!-- .br --> -num_valuators: CARD8 -<!-- .br --> -valuators: LISTOFINT32 -<!-- .br --> -Errors: Length, Device, Match, Value -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -status: {Success, AlreadyGrabbed}</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request initializes the specified valuators on the specified extension -input device. Valuators are numbered beginning with zero. Only the valuators -in the range specified by first_valuator and num_valuators are set. If the -number of valuators supported by the device is less than the expression -first_valuator + num_valuators, a <emphasis remap='B'>Value</emphasis> error will result.</para> -<para>If the request succeeds, <emphasis remap='B'>Success</emphasis> is returned. If the specifed device is -grabbed by some other client, the request will fail and a status of -<emphasis remap='B'>AlreadyGrabbed</emphasis> will be returned.</para> -</sect2> -<sect2 id='getting_input_device_controls'><title>Getting Input Device Controls</title> -<para>GetDeviceControl -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -control: XID -<!-- .br --> -Errors: Length, Device, Match, Value -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -controlState: {DeviceState}</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>where</para> -<!-- .in +.5i --> -<!-- .br --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DeviceState:</entry> - <entry align='left'>DeviceResolutionState</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>Errors: Length, Device, Match, Value</para> -<para>This request returns the current state of the specified device control. -The device control must be supported by the target server and device or an -error will result.</para> -<para>If the request is successful, a pointer to a generic DeviceState -structure will be returned. The information returned varies according to -the specified control and is mapped by a structure appropriate for that -control.</para> -<para>GetDeviceControl will fail with a BadValue error if the server does not support -the specified control. It will fail with a BadMatch error if the device -does not support the specified control.</para> -<para>Supported device controls and the information returned for them include:</para> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DEVICE_RESOLUTION:</entry> - <entry align='left'><para>[control: CARD16 -<!-- .br --> - length: CARD16 -<!-- .br --> - num_valuators: CARD8 -<!-- .br --> - resolutions: LISTofCARD32 -<!-- .br --> - min_resolutions: LISTofCARD32 -<!-- .br --> - max_resolutions: LISTofCARD32]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<para>This device control returns a list of valuators and the range of valid -resolutions allowed for each. Valuators are numbered beginning with 0. -Resolutions for all valuators on the device are returned. -For each valuator i on the device, resolutions[i] returns the current setting -of the resolution, min_resolutions[i] returns the minimum valid setting, -and max_resolutions[i] returns the maximum valid setting.</para> -<para>When this control is specified, XGetDeviceControl will fail with a BadMatch -error if the specified device has no valuators. -ChangeDeviceControl -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -XID: controlId -<!-- .br --> -control: DeviceControl</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>where</para> -<!-- .in +.5i --> -<!-- .br --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DeviceControl:</entry> - <entry align='left'>DeviceResolutionControl</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>Errors: Length, Device, Match, Value -<!-- .br --> -=> -<!-- .in +.5i --> -status: {Success, DeviceBusy, AlreadyGrabbed}</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>ChangeDeviceControl changes the specifed device control according to the values -specified in the DeviceControl structure. The device control must be supported -by the target server and device or an error will result.</para> -<para>The information passed with this request varies according to the specified -control and is mapped by a structure appropriate for that control.</para> -<para>ChangeDeviceControl will fail with a BadValue error if the server does not -support the specified control. It will fail with a BadMatch error if the -server supports the specified control, but the requested device does not. -The request will fail and return a status of DeviceBusy if another client -already has the device open with a device control state that conflicts with -the one specified in the request. It will fail with a status of -AlreadyGrabbed if some other client has grabbed the specified device. If -the request succeeds, Success is returned. If it fails, the device control -is left unchanged.</para> -<para>Supported device controls and the information specified for them include:</para> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DEVICE_RESOLUTION:</entry> - <entry align='left'><para>[control: CARD16 -<!-- .br --> - length: CARD16 -<!-- .br --> - first_valuator: CARD8 -<!-- .br --> - num_valuators: CARD8 -<!-- .br --> - resolutions: LISTofCARD32]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<para>This device control changes the resolution of the specified valuators -on the specified extension input device. Valuators are numbered beginning -with zero. Only the valuators in the range specified by first_valuator -and num_valuators are set. A value of -1 in the resolutions list indicates -that the resolution for this valuator is not to be changed. num_valuators -specifies the number of valuators in the resolutions list.</para> -<para>When this control is specified, XChangeDeviceControl will fail with a BadMatch -error if the specified device has no valuators. If a resolution is specified -that is not within the range of valid values (as returned by XGetDeviceControl) -the request will fail with a BadValue error. If the number of valuators -supported by the device is less than the expression first_valuator + -num_valuators, a BadValue error will result.</para> -<para>If the request fails for any reason, none of the valuator resolutions will be -changed.</para> -</sect2> -<sect2 id='selecting_extension_device_events'><title>Selecting Extension Device Events</title> -<para>Extension input events are selected using the <emphasis remap='B'>SelectExtensionEvent</emphasis> -request. -SelectExtensionEvent -<!-- .in .5i --> -window: WINDOW -<!-- .br --> -interest: LISTofEVENTCLASS -<!-- .br --> -Errors: Window, Class, Access</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request specifies to the server the events within the specified window -which are of interest to the client. As with the core <emphasis remap='B'>XSelectInput</emphasis> -function, multiple clients can select input on the same window.</para> -<para><emphasis remap='B'>XSelectExtensionEvent</emphasis> requires a list of <emphasis remap='I'>event classes</emphasis>. -An event class is a 32-bit number that combines an event type and -device id, and is used to indicate which event a client wishes to -receive and from which device it wishes to receive it. Macros -are provided to obtain event classes from the data returned by -the <emphasis remap='B'>XOpenDevice</emphasis> request. The names of these macros correspond -to the desired events, i.e. the <emphasis remap='B'>DeviceKeyPress</emphasis> is used to -obtain the event class for <emphasis remap='B'>DeviceKeyPress</emphasis> events. The syntax -of the macro invocation is: -DeviceKeyPress (device, event_type, event_class); -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -event_type: INT -<!-- .br --> -event_class: INT</para> -<!-- .in \-.5i --> -<!-- .br --> -<para>The value returned in <emphasis remap='B'>event_type</emphasis> is the value that will be contained in -the event type field of the <emphasis remap='B'>XDeviceKeyPressEvent</emphasis> when it is received by -the client. The value returned in <emphasis remap='B'>event_class</emphasis> is the value that should -be passed in making an <emphasis remap='B'>XSelectExtensionEvent</emphasis> request to receive -<emphasis remap='B'>DeviceKeyPress</emphasis> events.</para> -<para>For <emphasis remap='B'>DeviceButtonPress</emphasis> events, the client may specify whether -or not an implicit passive grab should be done when the button is -pressed. If the client wants to guarantee that it will receive -a <emphasis remap='B'>DeviceButtonRelease</emphasis> event for each <emphasis remap='B'>DeviceButtonPress</emphasis> -event it receives, it should specify the <emphasis remap='B'>DeviceButtonPressGrab</emphasis> -event class as well as the <emphasis remap='B'>DeviceButtonPress</emphasis> event class. -This restricts the client in that only one client at a time -may request <emphasis remap='B'>DeviceButtonPress</emphasis> events from the same device and -window if any client specifies this class.</para> -<para>If any client has specified the <emphasis remap='B'>DeviceButtonPressGrab</emphasis> class, any requests -by any other client that specify the same device and window and specify -<emphasis remap='B'>DeviceButtonPress</emphasis> or <emphasis remap='B'>DeviceButtonPressGrab</emphasis> will -cause an <emphasis remap='B'>Access</emphasis> error to be generated.</para> -<para>If only the <emphasis remap='B'>DeviceButtonPress</emphasis> class is specified, no implicit -passive grab will be done when a button is pressed on the device. -Multiple clients may use this class to specify the same device and -window combination.</para> -<para>A client may also specify the <emphasis remap='B'>DeviceOwnerGrabButton</emphasis> class. If it has -specified both the <emphasis remap='B'>DeviceButtonPressGrab</emphasis> and the -<emphasis remap='B'>DeviceOwnerGrabButton</emphasis> classes, implicit passive grabs will activate -with owner_events set to <emphasis remap='B'>True</emphasis>. If only the -<emphasis remap='B'>DeviceButtonPressGrab</emphasis> class is specified, implicit passive grabs will -activate with owner_events set to <emphasis remap='B'>False</emphasis>.</para> -<para>The client may select <emphasis remap='B'>DeviceMotion</emphasis> events only when a -button is down. It does this by specifying the event classes -<emphasis remap='B'>Button1Motion</emphasis> through <emphasis remap='B'>Button5Motion</emphasis>, or <emphasis remap='B'>ButtonMotion</emphasis>. -An input device will only support -as many button motion classes as it has buttons.</para> -</sect2> -<sect2 id='determining_selected_events'><title>Determining Selected Events</title> -<para>To determine which extension events are currently selected from a given -window, use <emphasis remap='B'>GetSelectedExtensionEvents</emphasis>. -GetSelectedExtensionEvents -<!-- .in .5i --> -window: WINDOW -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -<!-- .br --> -this-client: LISTofEVENTCLASS -<!-- .br --> -all-clients: LISTofEVENTCLASS -<!-- .br --> -Errors: Window</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request returns two lists specifying the events selected on the specified -window. One list gives the extension events selected by this client from -the specified window. The other list gives the extension events selected by -all clients from the specified window. This information is equivalent -to that returned by your-event-mask and all-event-masks in a -<emphasis remap='B'>GetWindowAttributes</emphasis> request.</para> -</sect2> -<sect2 id='controlling_event_propagation'><title>Controlling Event Propagation</title> -<para>Extension events propagate up the window hierarchy in the same manner -as core events. If a window is not interested in an extension event, -it usually propagates to the closest ancestor that is interested, -unless the dont_propagate list prohibits it. -Grabs of extension devices may alter the set of windows that receive a -particular extension event.</para> -<para>Client programs may control extension event propagation through the use -of the following two requests.</para> -<para><emphasis remap='B'>XChangeDeviceDontPropagateList</emphasis> adds an event to or deletes an event from -the do_not_propagate list of extension events for the specified window. This -list is maintained for the life of the window, and is not altered if the -client terminates.</para> -<para>ChangeDeviceDontPropagateList -<!-- .in .5i --> -window: WINDOW -<!-- .br --> -eventclass: LISTofEVENTCLASS -<!-- .br --> -mode: {AddToList, DeleteFromList} -<!-- .br --> -Errors: Window, Class, Mode</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This function modifies the list specifying the events that are not propagated -to the ancestors of the specified window. You may use the modes <emphasis remap='B'>AddToList</emphasis> -or <emphasis remap='B'>DeleteFromList</emphasis>. -GetDeviceDontPropagateList -<!-- .in .5i --> -window: WINDOW -<!-- .br --> -Errors: Window -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -dont-propagate-list: LISTofEVENTCLASS</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This function returns a list specifying the events that are not propagated -to the ancestors of the specified window.</para> -</sect2> -<sect2 id='sending_extension_events'><title>Sending Extension Events</title> -<para>One client program may send an event to another via the -<emphasis remap='B'>XSendExtensionEvent</emphasis> function.</para> -<para>The event in the <emphasis remap='B'>XEvent</emphasis> structure must be one of the events defined -by the input extension, so that the X server can correctly byte swap the -contents as necessary. The contents of the event are otherwise unaltered -and unchecked by the X server except to force send_event to <emphasis remap='B'>True</emphasis> -in the forwarded event and to set the sequence number in the event correctly.</para> -<para>XSendExtensionEvent returns zero if the conversion-to-wire protocol -failed, otherwise it returns nonzero. -SendExtensionEvent -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -destination: WINDOW -<!-- .br --> -propagate: BOOL -<!-- .br --> -eventclass: LISTofEVENTCLASS -<!-- .br --> -event: XEVENT -<!-- .in \-.5i --> -<!-- .br --> -Errors: Device, Value, Class, Window</para> -</sect2> -<sect2 id='getting_motion_history'><title>Getting Motion History</title> -<para>GetDeviceMotionEvents -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -start, stop: TIMESTAMP or CurrentTime -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -nevents_return: CARD32 -<!-- .br --> -mode_return: {Absolute, Relative} -<!-- .br --> -axis_count_return: CARD8 -<!-- .br --> -events: LISTofDEVICETIMECOORD -<!-- .br --> -<!-- .in \-.5i --> -where</para> -<!-- .br --> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>DEVICETIMECOORD:</entry> - <entry align='left'><para>[data:LISTofINT32 - time:TIMESTAMP]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<para>Errors: Device, Match</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request returns all positions in the device's motion history buffer -that fall between the specified start and stop times inclusive. If the -start time is in the future, or is later than the stop time, no positions -are returned.</para> -<para>The data field of the DEVICETIMECOORD structure is a sequence of -data items. Each item is of type INT32, and there is one data item -per axis of motion reported by the device. -The number of axes reported -by the device is returned in the axis_count variable.</para> -<para>The value of the data items depends on the mode of the device, which -is returned in the mode variable. -If the mode is Absolute, the data items are the raw values -generated by the device. These may be scaled by the client program -using the maximum values that the device can generate for each axis -of motion that it reports. The maximum and minimum values for each -axis are reported by the <emphasis remap='B'>ListInputDevices</emphasis> request.</para> -<para>If the mode is Relative, the data items are the relative values -generated by the device. The client program must choose an initial -position for the device and maintain a current position by -accumulating these relative values.</para> -</sect2> -<sect2 id='changing_the_core_devices'><title>Changing The Core Devices</title> -<para>These requests are provided to change which physical device is used -as the X pointer or X keyboard.</para> -<para>Using these requests may change the characteristics of the core devices. -The new pointer device may have a different number of buttons than the -old one did, or the new keyboard device may have a different number of -keys or report a different range of keycodes. Client programs may be -running that depend on those characteristics. For example, a client -program could allocate an array based on the number of buttons on the -pointer device, and then use the button numbers received in button events -as indicies into that array. Changing the core devices could cause -such client programs to behave improperly or abnormally terminate.</para> -<para>These requests change the X keyboard or X pointer device and generate -an <emphasis remap='B'>ChangeDeviceNotify</emphasis> event and a <emphasis remap='B'>MappingNotify</emphasis> event. -The <emphasis remap='B'>ChangeDeviceNotify</emphasis> event is sent only to those clients that have -expressed an interest in receiving that event via the -<emphasis remap='B'>XSelectExtensionEvent</emphasis> request. -The specified device becomes the -new X keyboard or X pointer device. The location of the core device -does not change as a result of this request.</para> -<para>These requests fail and return <emphasis remap='B'>AlreadyGrabbed</emphasis> if either the specified -device or the core device it would replace are grabbed by some other -client. They fail and return <emphasis remap='B'>GrabFrozen</emphasis> if either device is frozen -by the active grab of another client.</para> -<para>These requests fail with a <emphasis remap='B'>BadDevice</emphasis> error if the specified device is -invalid, or has not previously been opened via <emphasis remap='B'>OpenDevice</emphasis>. -To change the X keyboard device, use the <emphasis remap='B'>ChangeKeyboardDevice</emphasis> request. -The specified device must support input class Keys (as reported in the -ListInputDevices request) or the request will fail with a <emphasis remap='B'>BadMatch</emphasis> error. -Once the device has successfully replaced one of the core devices, it -is treated as a core device until it is in turn replaced by another -ChangeDevice request, or until the server terminates. The termination -of the client that changed the device will not cause it to change back. -Attempts to use the CloseDevice request to close the new core device will -fail with a BadDevice error.</para> -<para>The focus state of the new keyboard is the same as the focus state of the old -X keyboard. If the new keyboard was not initialized with a <emphasis remap='B'>FocusRec</emphasis>, -one is added by the <emphasis remap='B'>ChangeKeyboardDevice</emphasis> request. The X keyboard is -assumed to have a <emphasis remap='B'>KbdFeedbackClassRec</emphasis>. If the device was initialized -without a <emphasis remap='B'>KbdFeedbackClassRec</emphasis>, one will be added by this request. -The <emphasis remap='B'>KbdFeedbackClassRec</emphasis> will specify a null routine as the control -procedure and the bell procedure. -ChangeKeyboardDevice -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -Errors: Device, Match -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -status: Success, AlreadyGrabbed, Frozen</para> -<!-- .br --> -<para>To change the X pointer device, use the <emphasis remap='B'>ChangePointerDevice</emphasis> request. -The specified device must support input class Valuators (as reported in the -ListInputDevices request) or the request will fail with a BadMatch error. -The valuators to be used as the x- and y-axes of the pointer device must -be specified. Data from other valuators on the device will be ignored.</para> -<para>The X pointer device does not contain a <emphasis remap='B'>FocusRec</emphasis>. If the new -pointer was initialized with a <emphasis remap='B'>FocusRec</emphasis>, it is freed by the -<emphasis remap='B'>ChangePointerDevice</emphasis> request. The X pointer is assumed to have a -<emphasis remap='B'>ButtonClassRec</emphasis> and a <emphasis remap='B'>PtrFeedbackClassRec</emphasis>. If the device -was initialized without a <emphasis remap='B'>ButtonClassRec</emphasis> or a <emphasis remap='B'>PtrFeedbackClassRec</emphasis>, -one will be added by this request. The <emphasis remap='B'>ButtonClassRec</emphasis> added will -have no buttons, and the <emphasis remap='B'>PtrFeedbackClassRec</emphasis> will specify a null -routine as the control procedure.</para> -<para>If the specified device reports absolute positional information, and the -server implementation does not allow such a device to be used as the -X pointer, the request will fail with a <emphasis remap='B'>BadDevice</emphasis> error.</para> -<para>Once the device has successfully replaced one of the core devices, it -is treated as a core device until it is in turn replaced by another -ChangeDevice request, or until the server terminates. The termination -of the client that changed the device will not cause it to change back. -Attempts to use the CloseDevice request to close the new core device will -fail with a BadDevice error. -ChangePointerDevice -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -xaxis: CARD8 -<!-- .br --> -yaxis: CARD8 -Errors: Device, Match -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -status: Success, AlreadyGrabbed, Frozen</para> -<!-- .br --> -</sect2> -<sect2 id='event_synchronization_and_core_grabs'><title>Event Synchronization And Core Grabs</title> -<para>Implementation of the input extension requires an extension of the -meaning of event synchronization for the core grab requests. This is -necessary in order to allow window managers to freeze all input devices -with a single request.</para> -<para>The core grab requests require a <emphasis remap='B'>pointer_mode</emphasis> and <emphasis remap='B'>keyboard_mode</emphasis> -argument. The meaning of these modes is changed by the input extension. -For the <emphasis remap='B'>XGrabPointer</emphasis> and <emphasis remap='B'>XGrabButton</emphasis> requests, <emphasis remap='B'>pointer_mode</emphasis> -controls synchronization of the pointer device, and <emphasis remap='B'>keyboard_mode</emphasis> -controls the synchronization of all other input devices. -For the <emphasis remap='B'>XGrabKeyboard</emphasis> -and <emphasis remap='B'>XGrabKey</emphasis> requests, <emphasis remap='B'>pointer_mode</emphasis> controls the synchronization -of all input devices except the X keyboard, while <emphasis remap='B'>keyboard_mode</emphasis> controls -the synchronization of the keyboard. When using one of the core grab -requests, the synchronization of extension devices -is controlled by the mode specified for the device not being grabbed.</para> -</sect2> -<sect2 id='extension_active_grabs'><title>Extension Active Grabs</title> -<para>Active grabs of extension devices are supported via the <emphasis remap='B'>GrabDevice</emphasis> -request in the same way that core devices are grabbed using the core -GrabKeyboard request, except that a <emphasis remap='I'>Device</emphasis> is passed as -a function parameter. A list of events that the client wishes to -receive is also passed. The <emphasis remap='B'>UngrabDevice</emphasis> request allows a -previous active grab for an extension device to be released.</para> -<para>To grab an extension device, use the <emphasis remap='B'>GrabDevice</emphasis> request. -The device must have previously been opened using the <emphasis remap='B'>OpenDevice</emphasis> -request. -GrabDevice -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -grab-window: WINDOW -<!-- .br --> -owner-events: BOOL -<!-- .br --> -event-list: LISTofEVENTCLASS -<!-- .br --> -this-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -other-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -time:TIMESTAMP or CurrentTime -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable -<!-- .br --> -Errors: Device, Window, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<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>If owner-events is <emphasis remap='B'>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. -If owner-events is -<emphasis remap='B'>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. For either value of owner-events, unreported -events are discarded.</para> -<para>If this-device-mode is <emphasis remap='B'>Asynchronous</emphasis>, device event processing continues -normally. If the device is currently frozen by this client, then processing -of device events is resumed. If this-device-mode is <emphasis remap='B'>Synchronous</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 remap='B'>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 other-device-mode is <emphasis remap='B'>Asynchronous</emphasis>, event processing is -unaffected by activation of the grab. If other-device-mode is -<emphasis remap='B'>Synchronous</emphasis>, the state of all input devices except the grabbed one -(as seen by means of the protocol) appears to -freeze, and no further events are generated by the server until -the grabbing client issues a releasing <emphasis remap='B'>AllowDeviceEvents</emphasis> 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.</para> -<para>This request generates <emphasis remap='B'>DeviceFocusIn</emphasis> and <emphasis remap='B'>DeviceFocusOut</emphasis> events.</para> -<para>This request fails and returns:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para><emphasis remap='B'>AlreadyGrabbed</emphasis> -If the device is actively grabbed by some other client.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para><emphasis remap='B'>NotViewable</emphasis> -If grab-window is not viewable.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para><emphasis remap='B'>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 remap='B'>CurrentTime</emphasis> -is replaced by the current X server time.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para><emphasis remap='B'>Frozen</emphasis> -If the device is frozen by an active grab of another client.</para> -<para>If a grabbed device is closed by a client while an active grab by that -client is in -effect, that active grab will be released. Any passive grabs established by -that client will be released. If the device is frozen only by an active grab -of the requesting client, it is thawed.</para> -<para>To release a grab of an extension device, use <emphasis remap='B'>UngrabDevice</emphasis>. -UngrabDevice -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -time: TIMESTAMP or CurrentTime -<!-- .br --> -Errors: Device</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request releases the device if this client has it actively grabbed -(from either <emphasis remap='B'>GrabDevice</emphasis> or <emphasis remap='B'>GrabDeviceKey</emphasis>) and releases -any queued events. If any devices were frozen by the grab, -<emphasis remap='B'>UngrabDevice</emphasis> thaws them. -The request has no effect if the specified time is earlier -than the last-device-grab time or is later than the current server time.</para> -<para>This request generates <emphasis remap='B'>DeviceFocusIn</emphasis> and <emphasis remap='B'>DeviceFocusOut</emphasis> events.</para> -<para>An <emphasis remap='B'>UngrabDevice</emphasis> is performed automatically if the event window for an -active device grab becomes not viewable.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='passively_grabbing_a_key'><title>Passively Grabbing A Key</title> -<para>Passive grabs of buttons and keys on extension devices are supported -via the <emphasis remap='B'>GrabDeviceButton</emphasis> and <emphasis remap='B'>GrabDeviceKey</emphasis> requests. -These passive grabs are released via the <emphasis remap='B'>UngrabDeviceKey</emphasis> and -<emphasis remap='B'>UngrabDeviceButton</emphasis> requests.</para> -<para>To passively grab a single key on an extension device, use <emphasis remap='B'>GrabDeviceKey</emphasis>. -That device must have previously been opened using the <emphasis remap='B'>OpenDevice</emphasis> -request. -GrabDeviceKey</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -keycode: KEYCODE or AnyKey -<!-- .br --> -modifiers: SETofKEYMASK or AnyModifier -<!-- .br --> -modifier-device: DEVICE or NULL -<!-- .br --> -grab-window: WINDOW -<!-- .br --> -owner-events: BOOL -<!-- .br --> -event-list: LISTofEVENTCLASS -<!-- .br --> -this-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -other-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -Errors: Device, Match, Access, Window, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>GrabKey</emphasis> request. It establishes a -passive grab on a device. Consequently, In the future:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>IF the device is not grabbed and the specified key, which itself can be a -modifier key, is logically pressed when the specified modifier keys -logically are down on the specified modifier device (and no other -keys are down),</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>AND no other modifier keys logically are down,</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>AND EITHER the grab window is an ancestor of (or is) the focus window -OR the grab window is a descendent of the focus window and contains the pointer,</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>AND a passive grab on the same device and key combination does not exist on any -ancestor of the grab window,</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>THEN the device is actively grabbed, as for <emphasis remap='B'>GrabDevice</emphasis>, -the last-device-grab time is set to the time at which the key was pressed -(as transmitted in the <emphasis remap='B'>DeviceKeyPress</emphasis> event), and the -<emphasis remap='B'>DeviceKeyPress</emphasis> event is reported.</para> -<para>The interpretation of the remaining arguments is as for <emphasis remap='B'>GrabDevice</emphasis>. -The active grab is terminated automatically when logical state of the -device has the specified key released (independent of the logical state of the -modifier keys).</para> -<para>Note that the logical state of a device (as seen by means of the X protocol) -may lag the physical state if device event processing is frozen.</para> -<para>A modifier of <emphasis remap='B'>AnyModifier</emphasis> is equivalent to issuing the request for all -possible modifier combinations (including the combination of no modifiers). -It is not required that all modifiers specified have currently assigned -keycodes. -A key of <emphasis remap='B'>AnyKey</emphasis> is equivalent to issuing -the request for all possible keycodes. Otherwise, the key must be in -the range specified by min-keycode and max-keycode in the <emphasis remap='B'>ListInputDevices</emphasis> -request. If it is not within that range, <emphasis remap='B'>GrabDeviceKey</emphasis> generates a -<emphasis remap='B'>Value</emphasis> error.</para> -<para><emphasis remap='B'>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is -<emphasis remap='B'>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> -<para>An <emphasis remap='B'>Access</emphasis> error is generated if some other client has issued a -<emphasis remap='B'>GrabDeviceKey</emphasis> with the same device and key combination on the -same window. When using <emphasis remap='B'>AnyModifier</emphasis> or <emphasis remap='B'>AnyKey</emphasis>, -the request fails completely and the X server generates a <emphasis remap='B'>Access</emphasis> -error and no grabs are established if there is a conflicting grab for any -combination.</para> -<para>This request cannot be used to grab a key on the X keyboard device. -The core <emphasis remap='B'>GrabKey</emphasis> request should be used for that purpose.</para> -<para>To release a passive grab of a single key on an extension device, -use <emphasis remap='B'>UngrabDeviceKey</emphasis>. -UngrabDeviceKey</para> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -keycode: KEYCODE or AnyKey -<!-- .br --> -modifiers: SETofKEYMASK or AnyModifier -<!-- .br --> -modifier-device: DEVICE or NULL -<!-- .br --> -grab-window: WINDOW -<!-- .br --> -Errors: Device, Match, Window, Value, Alloc</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>UngrabKey</emphasis> request. It releases -the key combination on the specified window if it was grabbed by this -client. A modifier of <emphasis remap='B'>AnyModifier</emphasis> is equivalent to issuing the -request for all possible modifier combinations (including the combination -of no modifiers). A key of <emphasis remap='B'>AnyKey</emphasis> is equivalent to issuing the -request for all possible keycodes. This request has no effect on an -active grab.</para> -<para><emphasis remap='B'>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is -<emphasis remap='B'>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='passively_grabbing_a_button'><title>Passively Grabbing A Button</title> -<para>To establish a passive grab for a single button on an extension device, -use <emphasis remap='B'>GrabDeviceButton</emphasis>. -GrabDeviceButton</para> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -button: BUTTON or AnyButton -<!-- .br --> -modifiers: SETofKEYMASK or AnyModifier -<!-- .br --> -modifier-device: DEVICE or NULL -<!-- .br --> -grab-window: WINDOW -<!-- .br --> -owner-events: BOOL -<!-- .br --> -event-list: LISTofEVENTCLASS -<!-- .br --> -this-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -other-device-mode: {Synchronous, Asynchronous} -<!-- .br --> -Errors: Device, Match, Window, Access, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>GrabButton</emphasis> request. It -establishes an explicit passive grab for a button on an extension input -device. Since the server does not track extension devices, no cursor is -specified with this request. For the same reason, there is no -confine-to parameter. The device must have previously been opened using the -<emphasis remap='B'>OpenDevice</emphasis> request.</para> -<para>The <emphasis remap='B'>GrabDeviceButton</emphasis> request establishes a passive grab on a device. -Consequently, in the future,</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>IF the device is not grabbed and the specified button is logically pressed -when the specified modifier keys logically are down -(and no other buttons or modifier keys are down),</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>AND the grab window contains the device,</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>AND a passive grab on the same device and button/ key combination does not -exist on any ancestor of the grab window,</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>THEN the device is actively grabbed, as for <emphasis remap='B'>GrabDevice</emphasis>, -the last-grab time is set to the time at which the button was pressed -(as transmitted in the <emphasis remap='B'>DeviceButtonPress</emphasis> event), and the -<emphasis remap='B'>DeviceButtonPress</emphasis> event is reported.</para> -<para>The interpretation of the remaining arguments is as for -<emphasis remap='B'>GrabDevice</emphasis>. -The active grab is terminated automatically when logical state of the -device has all buttons released (independent of the logical state of -the modifier keys).</para> -<para>Note that the logical state of a device (as seen by means of the X protocol) -may lag the physical state if device event processing is frozen.</para> -<para>A modifier of <emphasis remap='B'>AnyModifier</emphasis> is equivalent to issuing the request for all -possible modifier combinations (including the combination of no modifiers). -It is not required that all modifiers specified have currently assigned -keycodes. A button of <emphasis remap='B'>AnyButton</emphasis> is equivalent to issuing the request -for all possible buttons. It is not required that the -specified button be assigned to a physical button.</para> -<para><emphasis remap='B'>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is -<emphasis remap='B'>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> -<para>An <emphasis remap='B'>Access</emphasis> error is generated if some other client has issued a -<emphasis remap='B'>GrabDeviceButton</emphasis> with the same device and button combination on the -same window. When using <emphasis remap='B'>AnyModifier</emphasis> or <emphasis remap='B'>AnyButton</emphasis>, the request -fails completely and the X server generates a <emphasis remap='B'>Access</emphasis> -error and no grabs are established if there is a conflicting grab for any -combination. The request has no effect on an active grab.</para> -<para>This request cannot be used to grab a button on the X pointer -device. The core <emphasis remap='B'>GrabButton</emphasis> request should be used for that -purpose.</para> -<para>To release a passive grab of a button on an extension device, use -<emphasis remap='B'>UngrabDeviceButton</emphasis>. -UngrabDeviceButton</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -button: BUTTON or AnyButton -<!-- .br --> -modifiers: SETofKEYMASK or AnyModifier -<!-- .br --> -modifier-device: DEVICE or NULL -<!-- .br --> -grab-window: WINDOW -<!-- .br --> -<!-- .br --> -Errors: Device, Match, Window, Value, Alloc</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core UngrabButton request. It releases -the passive button/key combination on the specified window if it was grabbed -by the client. A modifiers of <emphasis remap='B'>AnyModifier</emphasis> is equivalent to issuing the -request for all possible modifier combinations (including the combination -of no modifiers). A button of <emphasis remap='B'>AnyButton</emphasis> is equivalent to issuing the -request for all possible buttons. This request has no effect on an -active grab. The device must have previously been opened using the -<emphasis remap='B'>OpenDevice</emphasis> request otherwise a <emphasis remap='B'>Device</emphasis> error will be -generated.</para> -<para><emphasis remap='B'>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is -<emphasis remap='B'>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> -<para>This request cannot be used to ungrab a button on the X pointer -device. The core <emphasis remap='B'>UngrabButton</emphasis> request should be used for that -purpose.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='thawing_a_device'><title>Thawing A Device</title> -<para>To allow further events to be processed when a device has been frozen, -use <emphasis remap='B'>AllowDeviceEvents</emphasis>. -AllowDeviceEvents -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices, -ReplayThisdevice, AsyncAll, or SyncAll} -<!-- .br --> -time:TIMESTAMP or CurrentTime -<!-- .br --> -Errors: Device, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>The <emphasis remap='B'>AllowDeviceEvents</emphasis> request releases some queued events if the client -has caused a device to freeze. The request has no effect if the -specified time is earlier than the last-grab time of the most recent -active grab for the client, or if the specified time is later than the -current X server time.</para> -<para>The following describes the processing that occurs depending on what constant -you pass to the event-mode argument:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>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 client on -behalf of multiple separate grabs, AsyncThisDevice thaws for all. -AsyncThisDevice has no effect if the specified device is not frozen by the -client, but the device need not be grabbed by the client.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If the specified device is frozen and actively grabbed by the client, -event processing for that device continues normally until the next -button or key event is reported to the client. -At this time, -the specified device again appears to freeze. -However, if the reported event causes the grab to be released, -the specified device does not freeze. -SyncThisDevice has no effect if the specified device is not frozen by the client -or is not grabbed by the client.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If the specified device is actively grabbed by the client and is frozen -as the result of an event having been sent to the client (either from the -activation of a GrabDeviceButton or from a previous AllowDeviceEvents with -mode SyncThisDevice, but not from a Grab), -the grab is released and that event is completely reprocessed. -This time, however, the request ignores any passive grabs at or above -(towards the root) the grab-window of the grab just released. -The request has no effect if the specified device is not grabbed by the client -or if it is not frozen as the result of an event.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If the remaining devices are frozen by the client, -event processing for them continues as usual. -If the other devices are frozen multiple times by the client on behalf of -multiple separate grabs, -AsyncOtherDevices “thaws” for all. -AsyncOtherDevices has no effect if the devices are not frozen by the client, -but those devices need not be grabbed by the client.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If all devices are frozen by the client, -event processing (for all devices) continues normally until the next -button or key event is reported -to the client for a grabbed device (button event for the grabbed device, key -or motion event for the device), at which time the devices again appear to -freeze. However, if the reported event causes the grab to be released, -then the devices do not freeze (but if any device is still -grabbed, then a subsequent event for it will still cause all devices -to freeze). -SyncAll has no effect unless all devices -are frozen by the client. If any device is frozen twice -by the client on behalf of two separate grabs, -SyncAll "thaws" for both (but a subsequent freeze for SyncAll -will only freeze each device once).</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If all devices are frozen by the -client, event processing (for all devices) continues normally. -If any device is frozen multiple times by the client on behalf of multiple -separate grabs, AsyncAll "thaws" for all. -AsyncAll has no effect unless all -devices are frozen by the client.</para> -<para>AsyncThisDevice, SyncThisDevice, and ReplayThisDevice -have no effect on the processing of events from the remaining devices. -AsyncOtherDevices has no effect on the processing of events from the -specified device. -When the event_mode is SyncAll or AsyncAll, the -device parameter is ignored.</para> -<para>It is possible for several grabs of different devices (by the same -or different clients) to be active simultaneously. -If a device is frozen on behalf of any grab, -no event processing is performed for the device. -It is possible for a single device to be frozen because of several grabs. -In this case, -the freeze must be released on behalf of each grab before events can -again be processed.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='controlling_device_focus'><title>Controlling Device Focus</title> -<para>The current focus window for an extension input device can be -determined using the <emphasis remap='B'>GetDeviceFocus</emphasis> request. -Extension devices are focused using the <emphasis remap='B'>SetDeviceFocus</emphasis> -request in the same way that the keyboard is focused using -the <emphasis remap='B'>SetInputFocus</emphasis> request, except that a device is specified as -part of the request. One additional focus state, <emphasis remap='B'>FollowKeyboard</emphasis>, -is provided for extension devices.</para> -<para>To get the current focus state, revert state, and focus time of an extension device, -use <emphasis remap='B'>GetDeviceFocus</emphasis>. -GetDeviceFocus</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -focus: WINDOW, PointerRoot, FollowKeyboard, or None -<!-- .br --> -revert-to: Parent, PointerRoot, FollowKeyboard, or None -<!-- .br --> -focus-time: TIMESTAMP -<!-- .br --> -Errors: Device, Match</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request returns the current focus state, revert-to state, -and last-focus-time of an extension device.</para> -<para>To set the focus of an extension device, use <emphasis remap='B'>SetDeviceFocus</emphasis>. -SetDeviceFocus -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -focus: WINDOW, PointerRoot, FollowKeyboard, or None -<!-- .br --> -revert-to: Parent, PointerRoot, FollowKeyboard, or None -<!-- .br --> -focus-time: TIMESTAMP -<!-- .br --> -Errors: Device, Window, Value, Match</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request changes the focus for an extension input device and the -last-focus-change-time. The request has no effect if the specified -time is earlier than the last-focus-change-time or is later than the -current X server time. Otherwise, the last-focus-change-time is set to the -specified time, with CurrentTime replaced by the current server time.</para> -<para>The action taken by the server when this request is requested depends -on the value of the focus argument:</para> -<variablelist remap='IP'> - <varlistentry> - <term>•</term> - <listitem> -<para>If the focus argument is <emphasis remap='B'>None</emphasis>, all input events from this device -will be discarded until a new focus window is set. In this case, the -revert-to argument is ignored.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If a window ID is assigned to the focus argument, it becomes the focus -window of the device. If an input event from the device would normally -be reported to this window or to one of its inferiors, the event is -reported normally. Otherwise, the event is reported relative to the focus -window.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If you assign <emphasis remap='B'>PointerRoot</emphasis> to the focus argument, the focus window is -dynamically taken to be the root window of whatever screen the pointer is -on at each input event. In this case, the revert-to argument is ignored.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If you assign <emphasis remap='B'>FollowKeyboard</emphasis> to the focus argument, the focus window is -dynamically taken to be the same as the focus of the X keyboard at each -input event.</para> -<para>The specified focus window must be viewable at the time of the request -(else a <emphasis remap='B'>Match</emphasis> error). If the focus window later becomes not viewable, -the X server evaluates the revert-to argument -to determine the new focus window.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If you assign <emphasis remap='B'>RevertToParent</emphasis> -to the revert-to argument, the focus reverts to the parent -(or the closest viewable ancestor), and the new revert-to value is taken to -be <emphasis remap='B'>RevertToNone</emphasis>.</para> - </listitem> - </varlistentry> - <varlistentry> - <term>•</term> - <listitem> -<para>If you assign <emphasis remap='B'>RevertToPointerRoot</emphasis>, <emphasis remap='B'>RevertToFollowKeyboard</emphasis>, or <emphasis remap='B'>RevertToNone</emphasis> -to the revert-to argument, the focus reverts to that value.</para> -<para>When the focus reverts, -the X server generates <emphasis remap='B'>DeviceFocusIn</emphasis> -and <emphasis remap='B'>DeviceFocusOut</emphasis> -events, but the last-focus-change time is not affected.</para> -<para>This request causes the X server to generate <emphasis remap='B'>DeviceFocusIn</emphasis> and -<emphasis remap='B'>DeviceFocusOut</emphasis> events.</para> - </listitem> - </varlistentry> -</variablelist> -</sect2> -<sect2 id='controlling_device_feedback'><title>Controlling Device Feedback</title> -<para>To get the settings of feedbacks on an extension device, use -<emphasis remap='B'>GetFeedbackControl</emphasis>. This request provides functionality equivalent to -the core <emphasis remap='B'>GetKeyboardControl</emphasis> and <emphasis remap='B'>GetPointerControl</emphasis> functions. It -also provides a way to control displays associated with an input device that -are capable of displaying an integer or string. -GetFeedbackControl -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -num_feedbacks_return: CARD16 -<!-- .br --> -return_value: LISTofFEEDBACKSTATE -<!-- .br --> -where</para> -<!-- .br --> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>FEEDBACKSTATE:</entry> - <entry align='left'>{KbdFeedbackState, PtrFeedbackState, IntegerFeedbackState, StringFeedbackState, BellFeedbackState, LedFeedbackState}</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-1.0i --> -<para>Feedbacks are reported by class. Those -feedbacks that are reported for the core keyboard device are in class -<emphasis remap='B'>KbdFeedback</emphasis>, and are returned in the -<emphasis remap='B'>KbdFeedbackState</emphasis> structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS Kbd:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - key_click_percent: CARD8 -<!-- .br --> - bell_percent: CARD8 -<!-- .br --> - bell_pitch: CARD16 -<!-- .br --> - bell_duration: CARD16 -<!-- .br --> - led_value: BITMASK -<!-- .br --> - global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff} -<!-- .br --> - auto_repeats: LISTofCARD8]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Those feedbacks that are equivalent to those reported for the core pointer -are in feedback class <emphasis remap='B'>PtrFeedback</emphasis> and are reported in the -<emphasis remap='B'>PtrFeedbackState</emphasis> structure. The members of that structure are:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS Ptr:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - accelNumerator: CARD16 -<!-- .br --> - accelDenominator: CARD16 -<!-- .br --> - threshold: CARD16]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Some input devices provide a means of displaying an integer. Those devices -will support feedback class <emphasis remap='B'>IntegerFeedback</emphasis>, which is reported in the -<emphasis remap='B'>IntegerFeedbackState</emphasis> structure. The members of that structure are:</para> -<!-- .br --> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS Integer:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - resolution: CARD32 -<!-- .br --> - min-val: INT32 -<!-- .br --> - max-val: INT32]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>Some input devices provide a means of displaying a string. Those devices -will support feedback class <emphasis remap='B'>StringFeedback</emphasis>, which is reported in the -<emphasis remap='B'>StringFeedbackState</emphasis> structure. The members of that structure are:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS String:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - max_symbols: CARD16 -<!-- .br --> - num_keysyms_supported: CARD16 -<!-- .br --> - keysyms_supported: LISTofKEYSYM]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>Some input devices contain a bell. Those devices -will support feedback class <emphasis remap='B'>BellFeedback</emphasis>, which is reported in the -<emphasis remap='B'>BellFeedbackState</emphasis> structure. The members of that structure are:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS Bell:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - percent: CARD8 -<!-- .br --> - pitch: CARD16 -<!-- .br --> - duration: CARD16]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>The percent sets the base volume for the bell between 0 (off) and 100 -(loud) inclusive, if possible. Setting to -1 restores the default. -Other negative values generate a <emphasis remap='B'>Value</emphasis> error.</para> -<para>The pitch sets the pitch (specified in Hz) of the bell, if possible. -Setting to -1 restores the default. Other negative values generate a -<emphasis remap='B'>Value</emphasis> error.</para> -<para>The duration sets the duration (specified in milliseconds) of the -bell, if possible. Setting to -1 restores the default. -Other negative values generate a <emphasis remap='B'>Value</emphasis> error.</para> -<para>A bell generator connected with the console but not directly on the -device is treated as if it were part of the device. -Some input devices contain LEDs. Those devices -will support feedback class <emphasis remap='B'>Led</emphasis>, which is reported in the -<emphasis remap='B'>LedFeedbackState</emphasis> structure. The members of that structure are:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>CLASS Led:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - led_mask: BITMASK -<!-- .br --> - led_value: BITMASK]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<!-- .br --> -<para>Each bit in led_mask indicates that the corresponding led is supported by -the feedback. At most 32 LEDs per feedback are supported. -No standard interpretation of LEDs is defined.</para> -<para>This function will fail with a <emphasis remap='B'>BadMatch</emphasis> error if the device specified -in the request does not support feedbacks.</para> -<para>Errors: Device, Match</para> -<para>To change the settings of a feedback on an extension device, use -<emphasis remap='B'>ChangeFeedbackControl</emphasis>. -ChangeFeedbackControl -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -feedbackid: CARD8 -<!-- .br --> -value-mask: BITMASK -<!-- .br --> -value: FEEDBACKCONTROL -<!-- .br --> -Errors: Device, Match, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>.sp</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>FEEDBACKCONTROL:</entry> - <entry align='left'><para>{KBDFEEDBACKCONTROL, PTRFEEDBACKCONTROL, INTEGERFEEDBACKCONTROL, -STRINGFEEDBACKCONTROL, BELLFEEDBACKCONTROL, LEDFEEDBACKCONTROL}</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .br --> -<para>Feedback controls are grouped by class. Those feedbacks that are -equivalent to those supported by the core keyboard are controlled -by feedback class <emphasis remap='B'>KbdFeedbackClass</emphasis> using the <emphasis remap='B'>KbdFeedbackControl</emphasis> -structure. The members of that structure are:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>KBDFEEDBACKCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - key_click_percent: INT8 -<!-- .br --> - bell_percent: INT8 -<!-- .br --> - bell_pitch: INT16 -<!-- .br --> - bell_duration: INT16 -<!-- .br --> - led_mask: INT32 -<!-- .br --> - led_value: INT32 -<!-- .br --> - key: KEYCODE -<!-- .br --> - auto_repeat_mode: {AutoRepeatModeOn, -<!-- .br --> - AutoRepeatModeOff, AutoRepeatModeDefault}]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>The key_click_percent sets the volume for key clicks between 0 (off) and -100 (loud) inclusive, if possible. Setting to -1 restores the default. -Other negative values generate a <emphasis remap='B'>Value</emphasis> error.</para> -<para>If both auto_repeat_mode and key are specified, then the auto_repeat_mode -of that key is changed, if possible. If only auto_repeat_mode is specified, -then the global auto-repeat mode for the entire keyboard is changed, -if possible, without affecting the per-key settings. It is a <emphasis remap='B'>Match</emphasis> -error if a key is specified without an auto_repeat_mode.</para> -<para>The order in which controls are verified and altered is server-dependent. -If an error is generated, a subset of the controls may have been altered.</para> -<para>Those feedback controls equivalent to those of the core pointer are -controlled by feedback class <emphasis remap='B'>PtrFeedbackClass</emphasis> using the -<emphasis remap='B'>PtrFeedbackControl</emphasis> -structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>PTRFEEDBACKCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - accelNumerator: INT16 -<!-- .br --> - accelDenominator: INT16 -<!-- .br --> - threshold: INT16]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>The acceleration, expressed as a fraction, is a multiplier -for movement. For example, specifying 3/1 means the device moves three -times as fast as normal. The fraction may be rounded arbitrarily by the -X server. Acceleration only takes effect if the device moves more than -threshold pixels at once and only applies to the amount beyond the value -in the threshold argument. Setting a value to -1 restores the default. -The values of the do-accel and do-threshold arguments must be nonzero for -the device values to be set. Otherwise, the parameters will be unchanged. -Negative values generate a <emphasis remap='B'>Value</emphasis> error, as does a zero value -for the accel-denominator argument.</para> -<para>Some devices are capable of displaying an integer. This is done using -feedback class <emphasis remap='B'>IntegerFeedbackClass</emphasis> using the <emphasis remap='B'>IntegerFeedbackControl</emphasis> -structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>INTEGERCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - int_to_display: INT32]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Some devices are capable of displaying an string. This is done using -feedback class <emphasis remap='B'>StringFeedbackClass</emphasis> using the <emphasis remap='B'>StringFeedbackCtl</emphasis> -structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>STRINGCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - syms_to_display: LISTofKEYSYMS]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Some devices contain a bell. This is done using -feedback class <emphasis remap='B'>BellFeedbackClass</emphasis> using the <emphasis remap='B'>BellFeedbackControl</emphasis> -structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>BELLCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - percent: INT8 -<!-- .br --> - pitch: INT16 -<!-- .br --> - duration: INT16]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Some devices contain leds. These can be turned on and off using -the <emphasis remap='B'>LedFeedbackControl</emphasis> -structure. The members of that structure are as follows:</para> -<!-- .in +.5i --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>LEDCTL:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - length: CARD16 -<!-- .br --> - feedback id: CARD8 -<!-- .br --> - led_mask: BITMASK -<!-- .br --> - led_value: BITMASK]</para></entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .in \-.5i --> -<para>Errors: Device, Match, Value</para> -</sect2> -<sect2 id='ringing_a_bell_on_an_input_device'><title>Ringing a Bell on an Input Device</title> -<para>To ring a bell on an extension input device, use <emphasis remap='B'>DeviceBell</emphasis>. -DeviceBell</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -feedbackclass: CARD8 -<!-- .br --> -feedbackid: CARD8 -<!-- .br --> -percent: INT8 -<!-- .br --> -Errors: Device, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>Bell</emphasis> request. It rings the -specified bell on the specified input device feedback, using the specified -volume. -The specified volume is relative to the base volume for the feedback. -If the value for the percent argument is not in the range -100 to 100 -inclusive, a <emphasis remap='B'>Value</emphasis> error results. -The volume at which the bell rings when the percent argument is nonnegative is:</para> -<literallayout remap='DS'> - base - [(base * percent) / 100] + percent -</literallayout> <!-- remap='DE' --> -<para>The volume at which the bell rings -when the percent argument is negative is:</para> -<literallayout remap='DS'> - base + [(base * percent) / 100] -</literallayout> <!-- remap='DE' --> -<para>To change the base volume of the bell, use <emphasis remap='B'>ChangeFeedbackControl</emphasis> request.</para> -</sect2> -<sect2 id='controlling_device_encoding'><title>Controlling Device Encoding</title> -<para>To get the keyboard mapping of an extension device that has keys, use -<emphasis remap='B'>GetDeviceKeyMapping</emphasis>. -GetDeviceKeyMapping</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -first-keycode: KEYCODE -<!-- .br --> -count: CARD8 -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -keysyms-per-keycode: CARD8 -<!-- .br --> -keysyms: LISTofKEYSYM -<!-- .br --> -Errors: Device, Match, Value</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request returns the symbols for the specified number of keycodes for the -specified extension device, starting with the specified keycode. -The first-keycode must be greater than or equal to -min-keycode as returned in the connection setup (else a <emphasis remap='B'>Value</emphasis> error), -and</para> -<literallayout remap='DS'> -first-keycode + count - 1 -</literallayout> <!-- remap='DE' --> -<para>must be less than or equal to max-keycode as returned in the connection setup -(else a <emphasis remap='B'>Value</emphasis> error). -The number of elements in the keysyms list is</para> -<literallayout remap='DS'> -count * keysyms-per-keycode -</literallayout> <!-- remap='DE' --> -<para>and KEYSYM number N (counting from zero) for keycode K has an index -(counting from zero) of</para> -<literallayout remap='DS'> -(K - first-keycode) * keysyms-per-keycode + N -</literallayout> <!-- remap='DE' --> -<para>in keysyms. -The keysyms-per-keycode value is chosen arbitrarily by the server -to be large enough to report all requested symbols. -A special KEYSYM value of -<emphasis remap='B'>NoSymbol</emphasis> -is used to fill in unused elements for individual keycodes.</para> -<para>If the specified device has not first been opened by this client via -<emphasis remap='B'>OpenDevice</emphasis>, or if that device does not support input class Keys, -this request will fail with a <emphasis remap='B'>Device</emphasis> error.</para> -<para>To change the keyboard mapping of an extension device that has keys, use -<emphasis remap='B'>ChangeDeviceKeyMapping</emphasis>. -ChangeDeviceKeyMapping -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -first-keycode: KEYCODE -<!-- .br --> -keysyms-per-keycode: CARD8 -<!-- .br --> -keysyms: LISTofKEYSYM -<!-- .br --> -num_codes: CARD8 -<!-- .br --> -Errors: Device, Match, Value, Alloc</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>ChangeKeyMapping</emphasis> request. -It defines the symbols for the specified number of keycodes for the -specified extension device. -If the specified device has not first been opened by this client via -<emphasis remap='B'>OpenDevice</emphasis>, or if that device does not support input class Keys, -this request will fail with a <emphasis remap='B'>Device</emphasis> error.</para> -<para>The number of elements in the keysyms list must be a multiple of -keysyms_per_keycode. Otherwise, <emphasis remap='B'>ChangeDeviceKeyMapping</emphasis> generates -a <emphasis remap='B'>Length</emphasis> error. The specified first_keycode must be greater -than or equal to the min_keycode value returned by the <emphasis remap='B'>ListInputDevices</emphasis> -request, or this request will fail with a <emphasis remap='B'>Value</emphasis> error. In addition, -if the following expression is not less than the max_keycode value returned by -the <emphasis remap='B'>ListInputDevices</emphasis> request, the request will fail with a <emphasis remap='B'>Value</emphasis> -error:</para> -<literallayout remap='DS'> - first_keycode + (num_codes / keysyms_per_keycode) - 1 -</literallayout> <!-- remap='DE' --> -<para>To obtain the keycodes that are used as modifiers on an -extension device that has keys, use <emphasis remap='B'>GetDeviceModifierMapping</emphasis>. -GetDeviceModifierMapping -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -keycodes-per-modifier: CARD8 -<!-- .br --> -keycodes: LISTofKEYCODE -<!-- .br --> -Errors: Device, Match</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>GetModifierMapping</emphasis> request. -This request returns the keycodes of the keys being used as modifiers. -The number of keycodes in the list is 8*keycodes-per-modifier. -The keycodes are divided into eight sets, with each set containing -keycodes-per-modifier elements. The sets are assigned in order to the -modifiers <emphasis remap='B'>Shift</emphasis>, <emphasis remap='B'>Lock</emphasis>, <emphasis remap='B'>Control</emphasis>, <emphasis remap='B'>Mod1</emphasis>, <emphasis remap='B'>Mod2</emphasis>, -<emphasis remap='B'>Mod3</emphasis>, <emphasis remap='B'>Mod4</emphasis>, and <emphasis remap='B'>Mod5</emphasis>. The keycodes-per-modifier value is -chosen arbitrarily by the server; zeroes are used to fill in unused elements -within each set. If only zero values are given in a set, the use of the -corresponding modifier has been disabled. The order of keycodes within -each set is chosen arbitrarily by the server.</para> -<para>To set which keycodes that are to be used as modifiers for an extension -device, use <emphasis remap='B'>SetDeviceModifierMapping</emphasis>. -SetDeviceModifierMapping</para> -<!-- .br --> -<!-- .in .5i --> -<para>device: DEVICE -<!-- .br --> -keycodes-per-modifier: CARD8 -<!-- .br --> -keycodes: LISTofKEYCODE -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .br --> -<!-- .in +.5i --> -status: {Success, Busy, Failed} -<!-- .br --> -Errors: Device, Match, Value, Alloc</para> -<!-- .in \-.5i --> -<para>This request is analogous to the core <emphasis remap='B'>SetModifierMapping</emphasis> request. -This request specifies the keycodes (if any) of the keys to be used as -modifiers. The number of keycodes in the list must be -8*keycodes-per-modifier (else a <emphasis remap='B'>Length</emphasis> error). The keycodes are -divided into eight sets, with the sets, with each set containing -keycodes-per-modifier elements. The sets are assigned in order to the -modifiers <emphasis remap='B'>Shift</emphasis>, <emphasis remap='B'>Lock</emphasis>, <emphasis remap='B'>Control</emphasis>, <emphasis remap='B'>Mod1</emphasis>, <emphasis remap='B'>Mod2</emphasis>, -<emphasis remap='B'>Mod3</emphasis>, <emphasis remap='B'>Mod4</emphasis>, and <emphasis remap='B'>Mod5</emphasis>. Only non-zero keycode values are -used within each set; zero values are ignored. All of the non-zero -keycodes must be in the range specified by min-keycode and max-keycode -in the <emphasis remap='B'>ListInputDevices</emphasis> request (else a <emphasis remap='B'>Value</emphasis> error). The order of -keycodes within a set does not matter. If no non-zero values are specified -in a set, the use of the corresponding modifier is disabled, and the -modifier bit will always be zero. Otherwise, the modifier bit will be -one whenever at least one of the keys in the corresponding set is in the down -position.</para> -<para>A server can impose restrictions on how modifiers can be changed (for example, -if certain keys do not generate up transitions in hardware or if multiple keys -per modifier are not supported). The status reply is <emphasis remap='B'>Failed</emphasis> -if some such restriction is violated, and none of the modifiers are changed.</para> -<para>If the new non-zero keycodes specified for a modifier differ from those -currently defined, and any (current or new) keys for that modifier are -logically in the down state, then the status reply is <emphasis remap='B'>Busy</emphasis>, -and none of the modifiers are changed.</para> -<para>This request generates a <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event on a -<emphasis remap='B'>Success</emphasis> status. The <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event will be sent only -to those clients that have expressed an interest in receiving that event -via the <emphasis remap='B'>XSelectExtensionEvent</emphasis> request.</para> -<para>A X server can impose restrictions on how modifiers can be changed, -for example, if certain keys do not generate up transitions in hardware -or if multiple modifier keys are not supported. If some such restriction -is violated, the status reply is -<emphasis remap='B'>MappingFailed</emphasis> , and none of the modifiers are changed. -If the new keycodes specified for a modifier differ from those -currently defined and any (current or new) keys for that modifier are -in the logically down state, the status reply is <emphasis remap='B'>MappingBusy</emphasis>, -and none of the modifiers are changed.</para> -</sect2> -<sect2 id='controlling_button_mapping'><title>Controlling Button Mapping</title> -<para>These requests are analogous to the core <emphasis remap='B'>GetPointerMapping</emphasis> -and <emphasis remap='B'>ChangePointerMapping</emphasis> requests. They allow a client to -determine the current mapping of buttons on an extension device, -and to change that mapping.</para> -<para>To get the current button mapping for an extension device, use -<emphasis remap='B'>GetDeviceButtonMapping</emphasis>. -GetDeviceButtonMapping -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -nmap: CARD8 -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -map_return: LISTofCARD8 -<!-- .br --> -Errors: Device, Match</para> -<!-- .in \-.5i --> -<!-- .br --> -<para>The <emphasis remap='B'>GetDeviceButtonMapping</emphasis> function returns the current mapping of -the buttons on the specified device. Elements of the list are indexed -starting from one. The length of the list indicates the number of -physical buttons. The nominal mapping is the identity mapping map[i]=i.</para> -<para><emphasis remap='B'>nmap</emphasis> indicates the number of elements in the <emphasis remap='B'>map_return</emphasis> -array. Only the first nmap entries will be copied by the library -into the map_return array.</para> -<para>To set the button mapping for an extension device, use -<emphasis remap='B'>SetDeviceButtonMapping</emphasis>. -SetDeviceButtonMapping -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -map: LISTofCARD8 -<!-- .br --> -nmap: CARD8 -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -status: CARD8 -<!-- .br --> -Errors: Device, Match, Value</para> -<!-- .in \-.5i --> -<!-- .br --> -<para>The <emphasis remap='B'>SetDeviceButtonMapping</emphasis> function sets the mapping of the specified -device and causes the X server to generate a <emphasis remap='B'>DeviceMappingNotify</emphasis> -event on a status of <emphasis remap='B'>MappingSuccess</emphasis>. Elements of the list are -indexed starting from one. The length of the list, -specified in <emphasis remap='B'>nmap</emphasis>, -must be the same as -<emphasis remap='B'>GetDeviceButtonMapping</emphasis> would return. Otherwise, -<emphasis remap='B'>SetDeviceButtonMapping</emphasis> generates a <emphasis remap='B'>Value</emphasis> error. A zero element -disables a buttons, and elements are not restricted in value by the -number of physical buttons. However, no two elements can have the -same nonzero value. Otherwise, this function generates a -<emphasis remap='B'>Value</emphasis> error. If any of the buttons to be altered are in the -down state, the status reply is <emphasis remap='B'>MappingBusy</emphasis> and the mapping is -not changed.</para> -</sect2> -<sect2 id='obtaining_the_state_of_a_device'><title>Obtaining The State Of A Device</title> -<para>To obtain vectors that describe the state of the keys, buttons and valuators -of an extension device, use <emphasis remap='B'>QueryDeviceState</emphasis>. -QueryDeviceState -<!-- .br --> -<!-- .in .5i --> -device: DEVICE -<!-- .br --> -<!-- .in \-.5i --> -=> -<!-- .in +.5i --> -device-id: CARD8 -<!-- .br --> -data: LISTofINPUTCLASS -<!-- .br --> -<!-- .in \-.5i --> -where</para> -<!-- .in +.5i --> -<!-- .br --> -<informaltable pgwide='0' frame='none'> - <tgroup cols='2' align='center'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>INPUTCLASS:</entry> - <entry align='left'>{VALUATOR, BUTTON, KEY}</entry> - </row> - <row> - <entry align='left'>.sp</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>CLASS VALUATOR:</entry> - <entry align='left'><para>[class: CARD8 -<!-- .br --> - num_valuators: CARD8 -<!-- .br --> -mode: CARD8 -<!-- .in +.5i --> -<!-- .br --> -#x01 device mode -<!-- .in +.5i --> -<!-- .br --> -(0 = Relative, 1 = Absolute) -<!-- .br --> -<!-- .in \-.5i --> -#x02 proximity state -<!-- .in +.5i --> -<!-- .br --> -(0 = InProximity, 1 = OutOfProximity) -<!-- .in \-1.0i --> -<!-- .br --> - valuators: LISTofINT32]</para></entry> - </row> - <row> - <entry align='left'>.br</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>.sp</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>CLASS BUTTON:</entry> - <entry align='left'>[class: CARD8 -<!-- .br --> - num_buttons: CARD8 -<!-- .br --> - buttons: LISTofCARD8]</entry> - </row> - <row> - <entry align='left'>.br</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>.sp</entry> - <entry align='left'></entry> - </row> - <row> - <entry align='left'>CLASS KEY:</entry> - <entry align='left'>[class: CARD8 -<!-- .br --> - num_keys: CARD8 -<!-- .br --> - keys: LISTofCARD8]</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<!-- .br --> -<para>Errors: Device</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>The <emphasis remap='B'>QueryDeviceState</emphasis> request returns the current logical state of the -buttons, keys, and valuators on the specified input device. -The <emphasis remap='I'>buttons</emphasis> and <emphasis remap='I'>keys</emphasis> arrays, byte N (from 0) contains the -bits for key or button 8N to 8N+7 with the least significant bit in the -byte representing key or button 8N.</para> -<para>If the device has valuators, a bit in the mode field indicates whether the -device is reporting Absolute or Relative data. If it is reporting Absolute -data, the valuators array will contain the current value of the valuators. -If it is reporting Relative data, the valuators array will contain undefined -data.</para> -<para>If the device reports proximity information, a bit in the mode field indicates -whether the device is InProximity or OutOfProximity.</para> -</sect2> -</sect1> -<sect1 id='events'><title>Events</title> -<para>The input extension creates input events analogous to the core input events. -These extension input events are generated by manipulating one of the -extension input devices.</para> -<sect2 id='button_key_and_motion_events'><title>Button, Key, and Motion Events</title> -<para>DeviceKeyPress -<!-- .br --> -DeviceKeyRelease -<!-- .br --> -DeviceButtonPress, -<!-- .br --> -DeviceButtonRelease -<!-- .br --> -DeviceMotionNotify</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -root, event: WINDOW -<!-- .br --> -child: Window or None -<!-- .br --> -same-screen: BOOL -<!-- .br --> -root-x, root-y, event-x, event-y: INT16 -<!-- .br --> -detail: <see below> -<!-- .br --> -state: SETofKEYBUTMASK -<!-- .br --> -time: TIMESTAMP</para> -<!-- .in \-.5i --> -<para>These events are generated when a key, button, or valuator logically changes state. -The generation of these logical changes may lag the physical changes, -if device event processing is frozen. Note that <emphasis remap='B'>DeviceKeyPress</emphasis> -and <emphasis remap='B'>DeviceKeyRelease</emphasis> are generated for all keys, even those mapped to modifier bits. -The “source” of the event is the window the pointer is in. -The window with respect to which the event is normally reported is found -by looking up the hierarchy (starting with the source window) -for the first window on which any client has selected interest in the event. -The actual window used for reporting can be modified by active grabs and -by the focus window.The window the event is reported with respect to is called -the “event” window.</para> -<para>The root is the root window of the “source” window, and root-x and root-y -are the pointer coordinates relative to root's origin at the time of the event. -Event is the “event” window. If the event window is on the same screen as -root, then event-x and event-y are the pointer coordinates relative to the -event window's origin. Otherwise, event-x and event-y are zero. If the -source window is an inferior of the event window, then child is set to -the child of the event window that is an ancestor of (or is) the source window. -Otherwise, it is set to None. The state component gives the logical state of -the buttons on the core X pointer and modifier keys on the core X keyboard -just before the event. -The detail component type varies with the event type:</para> -<informaltable pgwide='0' frame='all'> - <tgroup cols='2' align='center' colsep='1' rowsep='1'> - <colspec colname='c1'/> - <colspec colname='c2'/> - <tbody> - <row> - <entry align='left'>Event</entry> - <entry align='left'>Component</entry> - </row> - <row> - <entry align='left'><para>DeviceKeyPress, -<!-- .br --> -DeviceKeyRelease</para></entry> - <entry align='left'>KEYCODE</entry> - </row> - <row> - <entry align='left'>DeviceButtonPress, -<!-- .br --> -DeviceButtonRelease</entry> - <entry align='left'>BUTTON</entry> - </row> - <row> - <entry align='left'>DeviceMotionNotify</entry> - <entry align='left'>{ Normal , Hint }</entry> - </row> - </tbody> - </tgroup> -</informaltable> -<para>The granularity of motion events is not guaranteed, but a client selecting -for motion events is guaranteed to get at least one event when a valuator -changes. If <emphasis remap='B'>DeviceMotionHint</emphasis> is selected, the server is free to send -only one <emphasis remap='B'>DeviceMotionNotify</emphasis> event (with detail <emphasis remap='B'>Hint</emphasis>) to the -client for the event window, until either a key or button changes state, -the pointer leaves the event window, or the client issues a -<emphasis remap='B'>QueryDeviceState</emphasis> or <emphasis remap='B'>GetDeviceMotionEvents</emphasis> request.</para> -</sect2> -<sect2 id='devicevaluator_event'><title>DeviceValuator Event</title> -<para>DeviceValuator</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -device_state: SETofKEYBUTMASK -<!-- .br --> -num_valuators: CARD8 -<!-- .br --> -first_valuator: CARD8 -<!-- .br --> -valuators: LISTofINT32</para> -<!-- .in \-.5i --> -<para>DeviceValuator events are generated to contain valuator information for which -there is insufficient space in DeviceKey, DeviceButton, DeviceMotion, and -Proximity wire events. For events of these types, a second event of type -DeviceValuator follows immediately. The library combines these events into -a single event that a client can receive via XNextEvent. DeviceValuator -events are not selected for by clients, they only exist to contain information -that will not fit into some event selected by clients.</para> -<para>The device_state component gives the state of the -buttons and modifiers on the device generating the event.</para> -<para>Extension motion devices may report motion data for a variable number of -axes. The valuators array contains the values of all axes reported by the -device. If more than 6 axes are reported, more than one DeviceValuator event -will be sent by the server, and more than one DeviceKey, DeviceButton, -DeviceMotion, or Proximity event will be reported by the library. -Clients should examine the corresponding fields of the event reported by -the library to determine the total number of axes reported, and the first axis -reported in the current event. Axes are numbered beginning with zero.</para> -<para>For Button, Key and Motion events on a device reporting absolute motion data -the current value of the device's valuators is reported. For devices that -report relative data, Button and Key events may be followed by a DeviceValuator -event that contains 0s in the num_valuators field. In this case, only the -device_state component will have meaning.</para> -</sect2> -<sect2 id='device_focus_events'><title>Device Focus Events</title> -<para>DeviceFocusIn -<!-- .br --> -DeviceFocusOut</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -time: TIMESTAMP -<!-- .br --> -event: WINDOW -<!-- .br --> -mode: { Normal, WhileGrabbed, Grab, Ungrab} -<!-- .br --> -detail: { Ancestor, Virtual, Inferior, Nonlinear, NonlinearVirtual, Pointer, PointerRoot, None}</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>These events are generated when the input focus changes and are reported to -clients selecting <emphasis remap='B'>DeviceFocusChange</emphasis> for the specified device and window. -Events generated by <emphasis remap='B'>SetDeviceFocus</emphasis> when the device is not grabbed -have mode <emphasis remap='B'>Normal</emphasis>. Events generated by <emphasis remap='B'>SetDeviceFocus</emphasis> when the -device is grabbed have mode <emphasis remap='B'>WhileGrabbed</emphasis>. Events generated when a -device grab actives have mode <emphasis remap='B'>Grab</emphasis>, and events generated when a device -grab deactivates have mode <emphasis remap='B'>Ungrab</emphasis>.</para> -<para>All <emphasis remap='B'>DeviceFocusOut</emphasis> events caused by a window unmap are generated after -any <emphasis remap='B'>UnmapNotify</emphasis> event, but the ordering of <emphasis remap='B'>DeviceFocusOut</emphasis> with -respect to generated <emphasis remap='B'>EnterNotify</emphasis>, <emphasis remap='B'>LeaveNotify</emphasis>, -<emphasis remap='B'>VisibilityNotify</emphasis> and <emphasis remap='B'>Expose</emphasis> events is not constrained.</para> -<para><emphasis remap='B'>DeviceFocusIn</emphasis> and <emphasis remap='B'>DeviceFocusOut</emphasis> events are generated for -focus changes of extension devices in the same manner as focus events for -the core devices are generated.</para> -</sect2> -<sect2 id='device_state_notify_event'><title>Device State Notify Event</title> -<para>DeviceStateNotify</para> -<!-- .in .5i --> -<para>time: TIMESTAMP -<!-- .br --> -device: CARD8 -<!-- .br --> -num_keys: CARD8 -<!-- .br --> -num_buttons: CARD8 -<!-- .br --> -num_valuators: CARD8 -<!-- .br --> -classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass} -<!-- .in +.5i --> -<!-- .br --> -SetOfDeviceMode: -<!-- .in +.5i --> -<!-- .br --> -#x80 ProximityState -<!-- .in +.5i --> -<!-- .br --> -0 = InProxmity, 1 = OutOfProximity -<!-- .in \-.5i --> -<!-- .br --> -#x40 Device Mode -<!-- .in +.5i --> -<!-- .br --> -(0 = Relative, 1 = Absolute) -<!-- .br --> -<!-- .in \-1.0i --> -SetOfInputClass: -<!-- .in +.5i --> -<!-- .br --> -#x04 reporting valuators -<!-- .br --> -#x02 reporting buttons -<!-- .br --> -#x01 reporting keys -<!-- .in \-1.0i --> -<!-- .br --> -buttons: LISTofCARD8 -<!-- .br --> -keys: LISTofCARD8 -<!-- .br --> -valuators: LISTofCARD32</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>This event reports the state of the device just as in the -<emphasis remap='B'>QueryDeviceState</emphasis> request. This event is reported to clients selecting -<emphasis remap='B'>DeviceStateNotify</emphasis> for the device and window and is generated immediately -after every <emphasis remap='B'>EnterNotify</emphasis> and <emphasis remap='B'>DeviceFocusIn</emphasis>. If the device has -no more than 32 buttons, no more than 32 keys, and no more than 3 valuators, -This event can report the state of the device. If the device has more -than 32 buttons, the event will be immediately followed by a -DeviceButtonStateNotify event. If the device has more than 32 keys, the -event will be followed by a DeviceKeyStateNotify event. If the device has more -than 3 valuators, the event will be followed by one or more DeviceValuator -events.</para> -</sect2> -<sect2 id='device_keystate_and_buttonstate_notify_e'><title>Device KeyState and ButtonState Notify Events</title> -<para>DeviceKeyStateNotify</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -keys: LISTofCARD8</para> -<!-- .in \-.5i --> -<para>DeviceButtonStateNotify</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -buttons: LISTofCARD8</para> -<!-- .in \-.5i --> -<para>These events contain information about the state of keys and buttons on a -device that will not fit into the DeviceStateNotify wire event. These events -are not selected by clients, rather they may immediately follow a -DeviceStateNotify wire event and be combined with it into a single -DeviceStateNotify client event that a client may receive via XNextEvent.</para> -</sect2> -<sect2 id='devicemappingnotify_event'><title>DeviceMappingNotify Event</title> -<para>DeviceMappingNotify</para> -<!-- .in .5i --> -<para>time: TIMESTAMP -<!-- .br --> -device: CARD8 -<!-- .br --> -request: CARD8 -<!-- .br --> -first_keycode: CARD8 -<!-- .br --> -count: CARD8</para> -<!-- .in \-.5i --> -<para>This event reports a change in the mapping of keys, modifiers, or buttons on -an extension device. This event is reported to clients selecting -<emphasis remap='B'>DeviceMappingNotify</emphasis> for the device and window and is generated -after every client <emphasis remap='B'>SetDeviceButtonMapping</emphasis>, <emphasis remap='B'>ChangeDeviceKeyMapping</emphasis>, -or <emphasis remap='B'>ChangeDeviceModifierMapping</emphasis> request.</para> -</sect2> -<sect2 id='changedevicenotify_event'><title>ChangeDeviceNotify Event</title> -<para>ChangeDeviceNotify</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -time: TIMESTAMP -<!-- .br --> -request: CARD8</para> -<!-- .in \-.5i --> -<para>This event reports a change in the physical device being used as the core -X keyboard or X pointer device. -<emphasis remap='B'>ChangeDeviceNotify</emphasis> events are reported to clients selecting -<emphasis remap='B'>ChangeDeviceNotify</emphasis> for the device and window and is generated -after every client <emphasis remap='B'>ChangeKeyboardDevice</emphasis> -or <emphasis remap='B'>ChangePointerDevice</emphasis> request.</para> -</sect2> -<sect2 id='proximity_events'><title>Proximity Events</title> -<para>ProximityIn -<!-- .br --> -ProximityOut</para> -<!-- .in .5i --> -<para>device: CARD8 -<!-- .br --> -root, event: WINDOW -<!-- .br --> -child: Window or None -<!-- .br --> -same-screen: BOOL -<!-- .br --> -root-x, root-y, event-x, event-y: INT16 -<!-- .br --> -state: SETofKEYBUTMASK -<!-- .br --> -time: TIMESTAMP -<!-- .br --> -device-state: SETofKEYBUTMASK -<!-- .br --> -axis-count: CARD8 -<!-- .br --> -first-axis: CARD8 -<!-- .br --> -axis-data: LISTofINT32</para> -<!-- .br --> -<!-- .in \-.5i --> -<para>These events are generated by some devices (such as graphics tablets or -touchscreens) to indicate that a stylus has moved into or out of contact -with a positional sensing surface.</para> -<para>The “source” of the event is the window the pointer is in. -The window with respect to which the event is normally reported is found -by looking up the hierarchy (starting with the source window) -for the first window on which any client has selected interest in the event. -The actual window used for reporting can be modified by active grabs and -by the focus window.The window the event is reported with respect to is called -the “event” window.</para> -<para>The root is the root window of the “source” window, and root-x and root-y -are the pointer coordinates relative to root's origin at the time of the event. -Event is the “event” window. If the event window is on the same screen as -root, then event-x and event-y are the pointer coordinates relative to the -event window's origin. Otherwise, event-x and event-y are zero. If the -source window is an inferior of the event window, then child is set to -the child of the event window that is an ancestor of (or is) the source window. -Otherwise, it is set to None. The state component gives the logical state of -the buttons on the core X pointer and modifier keys on the core X keyboard -just before the event. The device-state component gives the state of the -buttons and modifiers on the device generating the event.</para> -<!-- .bp --> -</sect2> -</sect1> + <sect1 id="input_extension"><title>Input Extension</title> + <para> + <literallayout> + <emphasis> + X11 Input Extension Protocol Specification + Version 1.0 + X Consortium Standard + X Version 11, Release 6.8 + Mark Patrick, Ardent Computer + George Sachs, Hewlett-Packard + </emphasis> + </literallayout> + </para> + <para>Copyright © 1989, 1990, 1991 by Hewlett-Packard Company and Ardent + Computer</para> + <para>Permission to use, copy, modify, and distribute this documentation for + any purpose and without fee is hereby granted, provided that the above + copyright notice and this permission notice appear in all copies. + Ardent and Hewlett-Packard make no representations about the suitability + for any purpose of the information in this document. It is + provided "as is" without express or implied warranty. + Copyright © 1989, 1990, 1991, 1992 X Consortium</para> + <para>Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the “Software”), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions:</para> + <para>The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software.</para> + <para>THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN + AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN + CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</para> + <para>Except as contained in this notice, the name of the X Consortium shall not be + used in advertising or otherwise to promote the sale, use or other dealings + in this Software without prior written authorization from the X Consortium. + <emphasis remap='I'>X Window System</emphasis> is a trademark of The Open Group.</para> + <sect2> + <title>Input Extension Overview</title> + <para>This document defines an extension to the X11 protocol to support + input devices other than the core X keyboard and pointer. + An accompanying document defines a corresponding extension to Xlib + (similar extensions for languages other than C are anticipated). + This first section gives an overview of the input extension. The + next section defines the new protocol requests defined by the extension. + We conclude with a description of the new input events generated by + the additional input devices.</para> + </sect2> + <sect2 id='design_approach'> + <title>Design Approach</title> + <para>The design approach of the extension is to define requests + and events analogous to the core requests and events. This allows + extension input devices to be individually distinguishable from each other + and from the core input devices. These requests and events make use + of a device identifier and support the reporting of n-dimensional motion + data as well as other data that is not reportable via the core + input events.</para> + </sect2> + <sect2 id='core_input_devices'> + <title>Core Input Devices</title> + <para>The X server core protocol supports two input devices: a pointer and a + keyboard. The pointer device has two major functions. + First, it may be used to generate motion information + that client programs can detect. Second, it may also be used to indicate the + current location and focus of the X keyboard. To accomplish this, the server + echoes a cursor at the current position of the X pointer. Unless the X + keyboard has been explicitly focused, this cursor also shows the current + location and focus of the X keyboard.</para> + <para>The X keyboard is used to generate input that client programs can detect.</para> + <para>The X keyboard and X pointer are referred to in this document as + the <emphasis remap='I'>core devices</emphasis>, and the input + events they generate (<emphasis>KeyPress</emphasis>, + <emphasis>KeyRelease</emphasis>, + <emphasis>ButtonPress</emphasis>, + <emphasis>ButtonRelease</emphasis>, and + <emphasis>MotionNotify</emphasis>) are known as the + <emphasis remap='I'>core input events</emphasis>. All other + input devices are referred to as <emphasis remap='I'>extension + input devices</emphasis> and the input events they + generate are referred to as <emphasis remap='I'>extension + input events</emphasis>.</para> <para>This input extension + does not change the behavior or functionality of the + core input devices, core events, or core protocol requests, with the + exception of the core grab requests. These requests may affect the + synchronization of events from extension devices. See the explanation + in the section titled "Event Synchronization and Core + Grabs". + </para> + <para>Selection of the physical devices to be initially used by the server as the + core devices is left implementation-dependent. Requests are defined that + allow client programs to change which physical devices are used as the + core devices.</para> + </sect2> + <sect2 id='extension_input_devices'> + <title>Extension Input Devices</title> + <para>The input extension 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.</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 + <emphasis>ListInputDevices</emphasis> request, which will return a list of all devices that + can be opened by the X server. A client can then open one or more of these + devices using the <emphasis>OpenDevice</emphasis> request, specify what events they are + interested in receiving, and receive and process input events from extension + devices in the same way as events from the X keyboard and X pointer. + Input events from these devices are of extension types ( + <emphasis>DeviceKeyPress</emphasis>, + <emphasis>DeviceKeyRelease</emphasis>, + <emphasis>DeviceButtonPress</emphasis>, + <emphasis>DeviceButtonRelease</emphasis>, + <emphasis>DeviceMotionNotify</emphasis>, etc.) and + contain a device identifier so that events of the same type + coming from different input devices can be + distinguished.</para> + <para>Any kind of input device may be used as an extension input device. + Extension input devices may have 0 or more keys, 0 or more buttons, + and may report 0 or more axes of motion. Motion may be reported + as relative movements from a previous position or as an absolute + position. All valuators reporting motion information for a given + extension input device must report the same kind of motion information + (absolute or relative).</para> + <para>This extension is designed to accommodate new types of input devices that + may be added in the future. The protocol requests that refer to + specific characteristics of input devices organize that information + by <emphasis>input classes</emphasis>. Server implementors may add new + classes of input devices without changing the protocol requests. + Input classes are unique numbers registered with the X Consortium. + Each extension input device may support multiple input classes.</para> + <para>All extension input devices are treated like the core X keyboard in + determining their location and focus. The server does not track the + location of these devices on an individual basis, and therefore + does not echo a cursor to indicate their current location. + Instead, their location is determined by the location of the core X pointer. + Like the core X keyboard, some may be explicitly focused. If they are + not explicitly focused, their focus is determined by the location of the + core X pointer.</para> + <para>Input events reported by the server to a client are of fixed size (32 bytes). + In order to represent the change in state of an input device the extension + may need to generate a sequence of input events. A client side library + (such as Xlib) will typically take these raw input events and format + them into a form more convenient to the client.</para> + <sect3 id='event_classes'> + <title>Event Classes</title> + <para>In the core protocol a client registers interest in receiving certain + input events directed to a window by modifying that window's event-mask. + Most of the bits in the event mask are already used to specify interest + in core X events. The input extension specifies a different mechanism by which + a client can express interest in events generated by this extension.</para> + <para>When a client opens a extension input device via the + <emphasis>OpenDevice</emphasis> request, an + <emphasis>XDevice</emphasis> structure is + returned. Macros are provided that extract 32-bit numbers + called <emphasis>event classes</emphasis> from + that structure, that a client can use to register interest + in extension events via the + <emphasis>SelectExtensionEvent</emphasis> + request. The event class combines the desired event type + and device id, and may be thought of as the equivalent of + core event masks.</para> + </sect3> + <sect3 id='input_classes'> + <title>Input Classes</title> + <para>Some of the input extension requests divide input devices into classes + based on their functionality. This is intended to allow new classes of input + devices to be defined at a later time without changing the semantics of + these requests. The following input device classes are currently + defined:</para> + <variablelist remap='IP'> + <varlistentry> + <term><emphasis>KEY</emphasis></term> + <listitem> + <para>The device reports key events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>BUTTON</emphasis></term> + <listitem> + <para>The device reports button events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>VALUATOR</emphasis></term> + <listitem> + <para>The device reports valuator data in motion events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>PROXIMITY</emphasis></term> + <listitem> + <para>The device reports proximity events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>FOCUS</emphasis></term> + <listitem> + <para>The device can be focused and reports focus events.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>FEEDBACK</emphasis></term> + <listitem> + <para>The device supports feedbacks.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis>OTHER</emphasis></term> + <listitem> + <para>The <emphasis>ChangeDeviceNotify</emphasis>, + <emphasis>DeviceMappingNotify</emphasis>, and + <emphasis>DeviceStateNotify</emphasis> macros may be + invoked passing the <emphasis>XDevice</emphasis> + structure returned for this device.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Each extension input device may support multiple input classes. + Additional classes may be added in the future. + Requests that support multiple input classes, such as the + <emphasis>ListInputDevices</emphasis> function that lists all available input devices, + organize the data they return by input class. Client programs that + use these requests should not access data unless it matches a + class defined at the time those clients were compiled. In this way, + new classes can be added without forcing existing clients that use + these requests to be recompiled.</para> + </sect3> + </sect2> + </sect1> + <sect1 id='requests'> + <title>Requests</title> + <para>Extension input devices are accessed by client programs through the + use of new protocol requests. This section summarizes the new requests + defined by this extension. The syntax and type definitions used below + follow the notation used for the X11 core protocol.</para> + <sect2 id='getting_the_extension_version'> + <title>Getting the Extension Version</title> + <para>The <emphasis>GetExtensionVersion</emphasis> request + returns version information about the input extension. + <literallayout> + GetExtensionVersion + name: STRING + => + present: BOOL + protocol-major-version: CARD16 + protocol-minor-version: CARD16 + </literallayout> + + The protocol version numbers returned indicate the version of the + input extension supported by the target X server. The version + numbers can be compared to constants defined in the header file + <filename>XI.h</filename>. Each version is a superset of the + previous versions.</para> + </sect2> + <sect2 id='listing_available_devices'><title>Listing Available Devices</title> + <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 + <emphasis>ListInputDevices</emphasis> request, which will + return a list of all devices that can be opened by the X server. + <literallayout> + ListInputDevices + => + input-devices: ListOfDeviceInfo + </literallayout> + where + <literallayout> + DEVICEINFO: + [type: ATOM + id: CARD8 + num_classes: CARD8 + use: {IsXKeyboard, IsXPointer, IsExtensionDevice} + info: LISTofINPUTINFO + name: STRING8] + + INPUTINFO: {KEYINFO, BUTTONINFO, VALUATORINFO} + + KEYINFO: + [class: CARD8 + length: CARD8 + min-keycode: KEYCODE + max-keycode: KEYCODE + num-keys: CARD16] + + BUTTONINFO: + [class: CARD8 + length: CARD8 + num-buttons: CARD16] + + VALUATORINFO: + [class: CARD8 + length: CARD8 + num_axes: CARD8 + mode: SETofDEVICEMODE + motion_buffer_size: CARD32 + axes: LISTofAXISINFO] + + AXISINFO: + [resolution: CARD32 + min-val: CARD32 + max-val: CARD32] + + DEVICEMODE: {Absolute, Relative} + </literallayout> + </para> + <para>Errors: None</para> + <para> + This request returns a list of all devices that can be opened by the X + server, + including the core X keyboard and X pointer. Some implementations may open + all input devices as part of X initialization, while others may not open + an input device until requested to do so by a client program.</para> + <para>The information returned for each device is as follows:</para> + <variablelist> + <varlistentry><term>type</term> + <listitem> + <para>The <emphasis>type</emphasis> field is of type <emphasis>Atom</emphasis> and indicates the nature of the + device. Clients may determine device types by invoking the <emphasis>XInternAtom</emphasis> + request passing one of the names defined in the header file <filename>XI.h</filename>. The + following names have been defined to date:</para> + <literallayout remap='DS'> + <emphasis>MOUSE</emphasis> + <emphasis>TABLET</emphasis> + <emphasis>KEYBOARD</emphasis> + <emphasis>TOUCHSCREEN</emphasis> + <emphasis>TOUCHPAD</emphasis> + <emphasis>BUTTONBOX</emphasis> + <emphasis>BARCODE</emphasis> + <emphasis>KNOB_BOX</emphasis> + <emphasis>TRACKBALL</emphasis> + <emphasis>QUADRATURE</emphasis> + <emphasis>SPACEBALL</emphasis> + <emphasis>DATAGLOVE</emphasis> + <emphasis>EYETRACKER</emphasis> + <emphasis>CURSORKEYS</emphasis> + <emphasis>FOOTMOUSE</emphasis> + <emphasis>ID_MODULE</emphasis> + <emphasis>ONE_KNOB</emphasis> + <emphasis>NINE_KNOB</emphasis> + </literallayout> + </listitem> + </varlistentry> + <varlistentry><term>id</term> + <listitem> + <para>The <emphasis>id</emphasis> is a small cardinal value in the range 0-128 that uniquely + identifies the device. It is assigned to the device when it is initialized by + the server. Some implementations may not open an input device until requested + by a client program, and may close the device when the last client accessing + it requests that it be closed. + If a device is opened by a client program via <emphasis>XOpenDevice</emphasis>, + then closed via <emphasis>XCloseDevice</emphasis>, then opened again, it is not guaranteed + to have the same id after the second open request.</para> + </listitem> + </varlistentry> + <varlistentry><term>num_classes</term> + <listitem> + <para>The <emphasis>num_classes</emphasis> field is a small cardinal value in the range 0-255 + that specifies the number of input classes supported by the device for + which information is returned by <emphasis>ListInputDevices</emphasis>. Some input classes, + such as class <emphasis>Focus</emphasis> and class <emphasis>Proximity</emphasis> do not have any information + to be returned by <emphasis>ListInputDevices</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry><term>use</term> + <listitem> + <para>The <emphasis>use</emphasis> field specifies how the device is currently being used. If the + value is <emphasis>IsXKeyboard</emphasis>, the device is currently being used as the + X keyboard. If the value is <emphasis>IsXPointer</emphasis>, the device is currently + being used as the X pointer. If the value is <emphasis>IsXExtensionDevice</emphasis>, + the device is available for use as an extension device.</para> + </listitem> + </varlistentry> + <varlistentry><term>name</term> + <listitem> + <para>The <emphasis>name</emphasis> field contains a pointer to a null-terminated string that + corresponds to one of the defined device types.</para> + </listitem> + </varlistentry> + <varlistentry><term>InputInfo</term> + <listitem> + <para><emphasis>InputInfo</emphasis> is one of: <emphasis>KeyInfo</emphasis>, <emphasis>ButtonInfo</emphasis> or + <emphasis>ValuatorInfo</emphasis>. The first two fields are common to all three: + + <variablelist> + <varlistentry><term>class</term> + <listitem> + <para>The <emphasis>class</emphasis> field is a cardinal value in the range 0-255. It uniquely + identifies the class of input for which information is returned.</para> + </listitem> + </varlistentry> + <varlistentry><term>length</term> + <listitem> + <para>The <emphasis>length</emphasis> field is a cardinal value in the range 0-255. It specifies + the number of bytes of data that are contained in this input class. The + length includes the class and length fields.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>The remaining information returned for input class <emphasis>KEYCLASS</emphasis> is as follows: + <variablelist> + <varlistentry><term>min_keycode</term> + <listitem> + <para><emphasis>min_keycode</emphasis> is of type KEYCODE. It specifies the minimum keycode that + the device will report. The minimum keycode will not be smaller than 8.</para> + </listitem> + </varlistentry> + <varlistentry><term>max_keycode</term> + <listitem> + <para><emphasis>max_keycode</emphasis> is of type KEYCODE. It specifies the maximum keycode that + the device will report. The maximum keycode will not be larger than 255.</para> + </listitem> + </varlistentry> + <varlistentry><term>num_keys</term> + <listitem> + <para><emphasis>num_keys</emphasis> is a cardinal value that specifies the number of keys that the + device has.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>The remaining information returned for input class <emphasis>BUTTONCLASS</emphasis> is as + follows: + <variablelist> + <varlistentry><term>num_buttons</term> + <listitem> + <para><emphasis>num_buttons</emphasis> is a cardinal value that specifies the number of buttons + that the device has.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>The remaining information returned for input class <emphasis>VALUATORCLASS</emphasis> is as + follows: + <variablelist> + <varlistentry><term>mode</term> + <listitem> + <para><emphasis>mode</emphasis> is a constant that has one of the following values: + <emphasis>Absolute</emphasis> or <emphasis>Relative</emphasis>. Some devices + allow the mode to be changed dynamically via the <emphasis>SetDeviceMode</emphasis> request.</para> + </listitem> + </varlistentry> + <varlistentry><term>motion_buffer_size</term> + <listitem> + <para><emphasis>motion_buffer_size</emphasis> is a cardinal number that specifies the number of + elements that can be contained in the motion history buffer for the device.</para> + </listitem> + </varlistentry> + <varlistentry><term>axes</term> + <listitem> + <para>The <emphasis>axes</emphasis> field contains a pointer to an AXISINFO struture.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>The information returned for each axis reported by the device is: + <variablelist> + <varlistentry><term>resolution</term> + <listitem><para>The <emphasis>resolution</emphasis> is a cardinal value in counts/meter.</para> + </listitem> + </varlistentry> + <varlistentry><term>min_val</term> + <listitem><para>The <emphasis>min_val</emphasis> field is a cardinal value in that contains the minimum + value the device reports for this axis. For devices whose mode is + <emphasis>Relative</emphasis>, the min_val field will contain 0.</para> + </listitem> + </varlistentry> + <varlistentry><term>max_val</term> + <listitem><para>The <emphasis>max_val</emphasis> field is a cardinal value in that contains the maximum + value the device reports for this axis. For devices whose mode is + <emphasis>Relative</emphasis>, the max_val field will contain 0.</para> + </listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2 id='enabling_devices'><title>Enabling Devices</title> + <para>Client programs that wish to access an extension device must request that + the server open that device. This is done via the <emphasis>OpenDevice</emphasis> + request. + <literallayout> + OpenDevice + id: CARD8 + => + DEVICE: + [device_id: XID + num_classes: INT32 + classes: LISTofINPUTCLASSINFO] + + INPUTCLASSINFO: + [input_class: CARD8 + event_type_base: CARD8] + </literallayout> + </para> + <para>Errors: Device</para> + <para>This request returns the event classes to be used by the client to indicate + which events the client program wishes to receive. Each input class + may report several event classes. For example, input class <emphasis>Keys</emphasis> reports + <emphasis>DeviceKeyPress</emphasis> and <emphasis>DeviceKeyRelease</emphasis> event classes. Input classes + are unique numbers registered with the X Consortium. Input class + <emphasis>Other</emphasis> exists + to report event classes that are not specific to any one input class, + such as <emphasis>DeviceMappingNotify</emphasis>, <emphasis>ChangeDeviceNotify</emphasis>, and + <emphasis>DeviceStateNotify</emphasis>.</para> + <para>The information returned for each device is as follows:</para> + <variablelist> + <varlistentry><term>device_id</term> + <listitem> + <para>The <emphasis>device_id</emphasis> is a number that uniquely identifies the device.</para> + </listitem> + </varlistentry> + <varlistentry><term>num_classes</term> + <listitem> + <para>The <emphasis>num_classes</emphasis> field contains the number of input classes supported + by this device.</para> + </listitem> + </varlistentry> + </variablelist> + <para>For each class of input supported by the device, + the <emphasis>InputClassInfo</emphasis> structure contains the following information:</para> + <variablelist> + <varlistentry><term>input_class</term> + <listitem> + <para>The <emphasis>input_class</emphasis> is a small cardinal number that identifies the class + of input.</para> + </listitem> + </varlistentry> + <varlistentry><term>event_type_base</term> + <listitem> + <para>The <emphasis>event_type_base</emphasis> is a small cardinal number that specifies the + event type of one of the events reported by this input class. This information + is not directly used by client programs. Instead, the <emphasis>Device</emphasis> is used + by macros that return extension event types and event classes. This is + described in the section of this document entitled "Selecting Extension + Device Events".</para> + </listitem> + </varlistentry> + </variablelist> + <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> + <para>A client may open the same extension device more than once. Requests + after the first successful one return an additional <emphasis>XDevice</emphasis> structure + 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>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> + <para>If a client program terminates without closing a device, the server will + automatically close that device on behalf of the client. This does not + affect any other clients that may be accessing that + device. + <literallayout> + CloseDevice: + device: DEVICE + </literallayout> + Errors: Device + </para> + </sect2> + <sect2 id='changing_the_mode_of_a_device'><title>Changing The Mode Of A Device</title> + <para>Some devices are capable of reporting either relative or absolute motion + data. To change the mode of a device from relative to absolute, use the + <emphasis>SetDeviceMode</emphasis> request. The valid values are <emphasis>Absolute</emphasis> or + <emphasis>Relative</emphasis>.</para> + <para>This request will fail and return <emphasis>DeviceBusy</emphasis> if another client already + has the device open with a different mode. It will fail and return + <emphasis>AlreadyGrabbed</emphasis> if another client has the device grabbed. + The request will fail with + a <emphasis>BadMatch</emphasis> error if the requested mode is not supported by the device. + <literallayout> + SetDeviceMode + device:DEVICE + mode: {Absolute, Relative} + => + status: {Success, DeviceBusy, AlreadyGrabbed} + </literallayout> + Errors: Device, Match, Mode</para> + </sect2> + <sect2 id='initializing_valuators_on_an_input_device'><title>Initializing Valuators on an Input Device</title> + <para>Some devices that report absolute positional data can be initialized to a + starting value. Devices that are capable of reporting relative motion or + absolute positional data may require that their valuators be initialized + to a starting value after the mode of the device is changed to <emphasis>Absolute</emphasis>. + To initialize the valuators on such a device, use the <emphasis>SetDeviceValuators</emphasis> + request. + <literallayout> + SetDeviceValuators + device: DEVICE + first_valuator: CARD8 + num_valuators: CARD8 + valuators: LISTOFINT32 + => + status: {Success, AlreadyGrabbed} + </literallayout> + Errors: Length, Device, Match, Value</para> + <para>This request initializes the specified valuators on the specified extension + input device. Valuators are numbered beginning with zero. Only the valuators + in the range specified by first_valuator and num_valuators are set. If the + number of valuators supported by the device is less than the expression + first_valuator + num_valuators, a <emphasis>Value</emphasis> error will result.</para> + <para>If the request succeeds, <emphasis>Success</emphasis> is returned. If the specifed device is + grabbed by some other client, the request will fail and a status of + <emphasis>AlreadyGrabbed</emphasis> will be returned.</para> + </sect2> + <sect2 id='getting_input_device_controls'><title>Getting Input Device Controls</title> + <para> + <literallayout> + GetDeviceControl + device: DEVICE + control: XID + => + controlState: {DeviceState} + </literallayout> + where + <literallayout> + DeviceState: DeviceResolutionState + </literallayout> + Errors: Length, Device, Match, Value</para> + <para>This request returns the current state of the specified device control. + The device control must be supported by the target server and device or an + error will result.</para> + <para>If the request is successful, a pointer to a generic DeviceState + structure will be returned. The information returned varies according to + the specified control and is mapped by a structure appropriate for that + control.</para> + <para>GetDeviceControl will fail with a BadValue error if the server does not support + the specified control. It will fail with a BadMatch error if the device + does not support the specified control.</para> + <para>Supported device controls and the information returned for them include: + <literallayout> + DEVICE_RESOLUTION: + [control: CARD16 + length: CARD16 + num_valuators: CARD8 + resolutions: LISTofCARD32 + min_resolutions: LISTofCARD32 + max_resolutions: LISTofCARD32] + </literallayout> + This device control returns a list of valuators and the range of valid + resolutions allowed for each. Valuators are numbered beginning with 0. + Resolutions for all valuators on the device are returned. + For each valuator i on the device, resolutions[i] returns the current setting + of the resolution, min_resolutions[i] returns the minimum valid setting, + and max_resolutions[i] returns the maximum valid setting.</para> + <para>When this control is specified, XGetDeviceControl will fail with a BadMatch + error if the specified device has no valuators. + <literallayout> + ChangeDeviceControl: + device: DEVICE + XID: controlId + control: DeviceControl + </literallayout> + where + <literallayout> + DeviceControl: DeviceResolutionControl + => + status: {Success, DeviceBusy, AlreadyGrabbed} + </literallayout> + Errors: Length, Device, Match, Value</para> + <para>ChangeDeviceControl changes the specifed device control according to the values + specified in the DeviceControl structure. The device control must be supported + by the target server and device or an error will result.</para> + <para>The information passed with this request varies according to the specified + control and is mapped by a structure appropriate for that control.</para> + <para>ChangeDeviceControl will fail with a BadValue error if the server does not + support the specified control. It will fail with a BadMatch error if the + server supports the specified control, but the requested device does not. + The request will fail and return a status of DeviceBusy if another client + already has the device open with a device control state that conflicts with + the one specified in the request. It will fail with a status of + AlreadyGrabbed if some other client has grabbed the specified device. If + the request succeeds, Success is returned. If it fails, the device control + is left unchanged.</para> + <para>Supported device controls and the information specified for them include: + <literallayout> + DEVICE_RESOLUTION: + [control: CARD16 + length: CARD16 + first_valuator: CARD8 + num_valuators: CARD8 + resolutions: LISTofCARD32] + </literallayout> + This device control changes the resolution of the specified valuators + on the specified extension input device. Valuators are numbered beginning + with zero. Only the valuators in the range specified by first_valuator + and num_valuators are set. A value of -1 in the resolutions list indicates + that the resolution for this valuator is not to be changed. num_valuators + specifies the number of valuators in the resolutions list.</para> + <para>When this control is specified, XChangeDeviceControl will fail with a BadMatch + error if the specified device has no valuators. If a resolution is specified + that is not within the range of valid values (as returned by XGetDeviceControl) + the request will fail with a BadValue error. If the number of valuators + supported by the device is less than the expression first_valuator + + num_valuators, a BadValue error will result.</para> + <para>If the request fails for any reason, none of the valuator resolutions will be + changed.</para> + </sect2> + <sect2 id='selecting_extension_device_events'><title>Selecting Extension Device Events</title> + <para>Extension input events are selected using the <emphasis>SelectExtensionEvent</emphasis> + request. + <literallayout> + SelectExtensionEvent + interest: LISTofEVENTCLASS + window: WINDOW + </literallayout> + Errors: Window, Class, Access</para> + <para>This request specifies to the server the events within the specified window + which are of interest to the client. As with the core <emphasis>XSelectInput</emphasis> + function, multiple clients can select input on the same window.</para> + <para><emphasis>XSelectExtensionEvent</emphasis> requires a list of <emphasis remap='I'>event classes</emphasis>. + An event class is a 32-bit number that combines an event type and + device id, and is used to indicate which event a client wishes to + receive and from which device it wishes to receive it. Macros + are provided to obtain event classes from the data returned by + the <emphasis>XOpenDevice</emphasis> request. The names of these macros correspond + to the desired events, i.e. the <emphasis>DeviceKeyPress</emphasis> is used to + obtain the event class for <emphasis>DeviceKeyPress</emphasis> events. The syntax + of the macro invocation is: + <synopsis> + DeviceKeyPress (device, event_type, event_class); + device: DEVICE + event_type: INT + event_class: INT + </synopsis> + </para> + <para>The value returned in <emphasis>event_type</emphasis> is the value that will be contained in + the event type field of the <emphasis>XDeviceKeyPressEvent</emphasis> when it is received by + the client. The value returned in <emphasis>event_class</emphasis> is the value that should + be passed in making an <emphasis>XSelectExtensionEvent</emphasis> request to receive + <emphasis>DeviceKeyPress</emphasis> events.</para> + <para>For <emphasis>DeviceButtonPress</emphasis> events, the client may specify whether + or not an implicit passive grab should be done when the button is + pressed. If the client wants to guarantee that it will receive + a <emphasis>DeviceButtonRelease</emphasis> event for each <emphasis>DeviceButtonPress</emphasis> + event it receives, it should specify the <emphasis>DeviceButtonPressGrab</emphasis> + event class as well as the <emphasis>DeviceButtonPress</emphasis> event class. + This restricts the client in that only one client at a time + may request <emphasis>DeviceButtonPress</emphasis> events from the same device and + window if any client specifies this class.</para> + <para>If any client has specified the <emphasis>DeviceButtonPressGrab</emphasis> class, any requests + by any other client that specify the same device and window and specify + <emphasis>DeviceButtonPress</emphasis> or <emphasis>DeviceButtonPressGrab</emphasis> will + cause an <emphasis>Access</emphasis> error to be generated.</para> + <para>If only the <emphasis>DeviceButtonPress</emphasis> class is specified, no implicit + passive grab will be done when a button is pressed on the device. + Multiple clients may use this class to specify the same device and + window combination.</para> + <para>A client may also specify the <emphasis>DeviceOwnerGrabButton</emphasis> class. If it has + specified both the <emphasis>DeviceButtonPressGrab</emphasis> and the + <emphasis>DeviceOwnerGrabButton</emphasis> classes, implicit passive grabs will activate + with owner_events set to <emphasis>True</emphasis>. If only the + <emphasis>DeviceButtonPressGrab</emphasis> class is specified, implicit passive grabs will + activate with owner_events set to <emphasis>False</emphasis>.</para> + <para>The client may select <emphasis>DeviceMotion</emphasis> events only when a + button is down. It does this by specifying the event classes + <emphasis>Button1Motion</emphasis> through <emphasis>Button5Motion</emphasis>, or <emphasis>ButtonMotion</emphasis>. + An input device will only support + as many button motion classes as it has buttons.</para> + </sect2> + <sect2 id='determining_selected_events'><title>Determining Selected Events</title> + <para>To determine which extension events are currently selected from a given + window, use <emphasis>GetSelectedExtensionEvents</emphasis>. + <literallayout> + GetSelectedExtensionEvents + window: WINDOW + => + this-client: LISTofEVENTCLASS + all-clients: LISTofEVENTCLASS + </literallayout> + Errors: Window</para> + <para>This request returns two lists specifying the events selected on the specified + window. One list gives the extension events selected by this client from + the specified window. The other list gives the extension events selected by + all clients from the specified window. This information is equivalent + to that returned by your-event-mask and all-event-masks in a + <emphasis>GetWindowAttributes</emphasis> request.</para> + </sect2> + <sect2 id='controlling_event_propagation'><title>Controlling Event Propagation</title> + <para>Extension events propagate up the window hierarchy in the same manner + as core events. If a window is not interested in an extension event, + it usually propagates to the closest ancestor that is interested, + unless the dont_propagate list prohibits it. + Grabs of extension devices may alter the set of windows that receive a + particular extension event.</para> + <para>Client programs may control extension event propagation through the use + of the following two requests.</para> + <para><emphasis>XChangeDeviceDontPropagateList</emphasis> adds an event to or deletes an event from + the do_not_propagate list of extension events for the specified window. This + list is maintained for the life of the window, and is not altered if the + client terminates. + + <literallayout> + ChangeDeviceDontPropagateList + window: WINDOW + eventclass: LISTofEVENTCLASS + mode: {AddToList, DeleteFromList} + </literallayout> + Errors: Window, Class, Mode</para> + <para>This function modifies the list specifying the events that are not propagated + to the ancestors of the specified window. You may use the modes <emphasis>AddToList</emphasis> + or <emphasis>DeleteFromList</emphasis>. + <literallayout> + GetDeviceDontPropagateList + window: WINDOW + Errors: Window + => + dont-propagate-list: LISTofEVENTCLASS + </literallayout> + This function returns a list specifying the events that are not propagated + to the ancestors of the specified window.</para> + </sect2> + <sect2 id='sending_extension_events'><title>Sending Extension Events</title> + <para>One client program may send an event to another via the + <emphasis>XSendExtensionEvent</emphasis> function.</para> + <para>The event in the <emphasis>XEvent</emphasis> structure must be one of the events defined + by the input extension, so that the X server can correctly byte swap the + contents as necessary. The contents of the event are otherwise unaltered + and unchecked by the X server except to force send_event to <emphasis>True</emphasis> + in the forwarded event and to set the sequence number in the event correctly.</para> + <para>XSendExtensionEvent returns zero if the conversion-to-wire protocol + failed, otherwise it returns nonzero. + <literallayout> + SendExtensionEvent + device: DEVICE + destination: WINDOW + propagate: BOOL + eventclass: LISTofEVENTCLASS + event: XEVENT + </literallayout> + Errors: Device, Value, Class, Window</para> + </sect2> + <sect2 id='getting_motion_history'><title>Getting Motion History</title> + <para> + <literallayout> + GetDeviceMotionEvents + device: DEVICE + start, stop: TIMESTAMP or CurrentTime + => + nevents_return: CARD32 + mode_return: {Absolute, Relative} + axis_count_return: CARD8 + events: LISTofDEVICETIMECOORD + </literallayout> + where + <literallayout> + DEVICETIMECOORD: + [data: LISTofINT32 + time: TIMESTAMP] + </literallayout> + Errors: Device, Match</para> + <para>This request returns all positions in the device's motion history buffer + that fall between the specified start and stop times inclusive. If the + start time is in the future, or is later than the stop time, no positions + are returned.</para> + <para>The data field of the DEVICETIMECOORD structure is a sequence of + data items. Each item is of type INT32, and there is one data item + per axis of motion reported by the device. + The number of axes reported + by the device is returned in the axis_count variable.</para> + <para>The value of the data items depends on the mode of the device, which + is returned in the mode variable. + If the mode is Absolute, the data items are the raw values + generated by the device. These may be scaled by the client program + using the maximum values that the device can generate for each axis + of motion that it reports. The maximum and minimum values for each + axis are reported by the <emphasis>ListInputDevices</emphasis> request.</para> + <para>If the mode is Relative, the data items are the relative values + generated by the device. The client program must choose an initial + position for the device and maintain a current position by + accumulating these relative values.</para> + </sect2> + <sect2 id='changing_the_core_devices'><title>Changing The Core Devices</title> + <para>These requests are provided to change which physical device is used + as the X pointer or X keyboard.</para> + <para>Using these requests may change the characteristics of the core devices. + The new pointer device may have a different number of buttons than the + old one did, or the new keyboard device may have a different number of + keys or report a different range of keycodes. Client programs may be + running that depend on those characteristics. For example, a client + program could allocate an array based on the number of buttons on the + pointer device, and then use the button numbers received in button events + as indicies into that array. Changing the core devices could cause + such client programs to behave improperly or abnormally terminate.</para> + <para>These requests change the X keyboard or X pointer device and generate + an <emphasis>ChangeDeviceNotify</emphasis> event and a <emphasis>MappingNotify</emphasis> event. + The <emphasis>ChangeDeviceNotify</emphasis> event is sent only to those clients that have + expressed an interest in receiving that event via the + <emphasis>XSelectExtensionEvent</emphasis> request. + The specified device becomes the + new X keyboard or X pointer device. The location of the core device + does not change as a result of this request.</para> + <para>These requests fail and return <emphasis>AlreadyGrabbed</emphasis> if either the specified + device or the core device it would replace are grabbed by some other + client. They fail and return <emphasis>GrabFrozen</emphasis> if either device is frozen + by the active grab of another client.</para> + <para>These requests fail with a <emphasis>BadDevice</emphasis> error if the specified device is + invalid, or has not previously been opened via <emphasis>OpenDevice</emphasis>. + To change the X keyboard device, use the <emphasis>ChangeKeyboardDevice</emphasis> request. + The specified device must support input class Keys (as reported in the + ListInputDevices request) or the request will fail with a <emphasis>BadMatch</emphasis> error. + Once the device has successfully replaced one of the core devices, it + is treated as a core device until it is in turn replaced by another + ChangeDevice request, or until the server terminates. The termination + of the client that changed the device will not cause it to change back. + Attempts to use the CloseDevice request to close the new core device will + fail with a BadDevice error.</para> + <para>The focus state of the new keyboard is the same as the focus state of the old + X keyboard. If the new keyboard was not initialized with a <emphasis>FocusRec</emphasis>, + one is added by the <emphasis>ChangeKeyboardDevice</emphasis> request. The X keyboard is + assumed to have a <emphasis>KbdFeedbackClassRec</emphasis>. If the device was initialized + without a <emphasis>KbdFeedbackClassRec</emphasis>, one will be added by this request. + The <emphasis>KbdFeedbackClassRec</emphasis> will specify a null routine as the control + procedure and the bell procedure. + <literallayout> + ChangeKeyboardDevice + device: DEVICE + Errors: Device, Match + => + status: Success, AlreadyGrabbed, Frozen + </literallayout> + </para> + <para>To change the X pointer device, use the <emphasis>ChangePointerDevice</emphasis> request. + The specified device must support input class Valuators (as reported in the + ListInputDevices request) or the request will fail with a BadMatch error. + The valuators to be used as the x- and y-axes of the pointer device must + be specified. Data from other valuators on the device will be ignored.</para> + <para>The X pointer device does not contain a <emphasis>FocusRec</emphasis>. If the new + pointer was initialized with a <emphasis>FocusRec</emphasis>, it is freed by the + <emphasis>ChangePointerDevice</emphasis> request. The X pointer is assumed to have a + <emphasis>ButtonClassRec</emphasis> and a <emphasis>PtrFeedbackClassRec</emphasis>. If the device + was initialized without a <emphasis>ButtonClassRec</emphasis> or a <emphasis>PtrFeedbackClassRec</emphasis>, + one will be added by this request. The <emphasis>ButtonClassRec</emphasis> added will + have no buttons, and the <emphasis>PtrFeedbackClassRec</emphasis> will specify a null + routine as the control procedure.</para> + <para>If the specified device reports absolute positional information, and the + server implementation does not allow such a device to be used as the + X pointer, the request will fail with a <emphasis>BadDevice</emphasis> error.</para> + <para>Once the device has successfully replaced one of the core devices, it + is treated as a core device until it is in turn replaced by another + ChangeDevice request, or until the server terminates. The termination + of the client that changed the device will not cause it to change back. + Attempts to use the CloseDevice request to close the new core device will + fail with a BadDevice error. + <literallayout> + ChangePointerDevice + device: DEVICE + xaxis: CARD8 + yaxis: CARD8 + => + status: Success, AlreadyGrabbed, Frozen + </literallayout> + Errors: Device, Match</para> + </sect2> + <sect2 id='event_synchronization_and_core_grabs'><title>Event Synchronization And Core Grabs</title> + <para>Implementation of the input extension requires an extension of the + meaning of event synchronization for the core grab requests. This is + necessary in order to allow window managers to freeze all input devices + with a single request.</para> + <para>The core grab requests require a <emphasis>pointer_mode</emphasis> and <emphasis>keyboard_mode</emphasis> + argument. The meaning of these modes is changed by the input extension. + For the <emphasis>XGrabPointer</emphasis> and <emphasis>XGrabButton</emphasis> requests, <emphasis>pointer_mode</emphasis> + controls synchronization of the pointer device, and <emphasis>keyboard_mode</emphasis> + controls the synchronization of all other input devices. + For the <emphasis>XGrabKeyboard</emphasis> + and <emphasis>XGrabKey</emphasis> requests, <emphasis>pointer_mode</emphasis> controls the synchronization + of all input devices except the X keyboard, while <emphasis>keyboard_mode</emphasis> controls + the synchronization of the keyboard. When using one of the core grab + requests, the synchronization of extension devices + is controlled by the mode specified for the device not being grabbed.</para> + </sect2> + <sect2 id='extension_active_grabs'><title>Extension Active Grabs</title> + <para>Active grabs of extension devices are supported via the <emphasis>GrabDevice</emphasis> + request in the same way that core devices are grabbed using the core + GrabKeyboard request, except that a <emphasis remap='I'>Device</emphasis> is passed as + a function parameter. A list of events that the client wishes to + receive is also passed. The <emphasis>UngrabDevice</emphasis> request allows a + previous active grab for an extension device to be released.</para> + <para>To grab an extension device, use the <emphasis>GrabDevice</emphasis> request. + The device must have previously been opened using the <emphasis>OpenDevice</emphasis> + request. + <literallayout> + GrabDevice + device: DEVICE + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} + time:TIMESTAMP or CurrentTime + => + status: Success, AlreadyGrabbed, Frozen, InvalidTime, NotViewable + </literallayout> + Errors: Device, Window, 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>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. + 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. For either value of owner-events, unreported + events are discarded.</para> + <para>If this-device-mode is <emphasis>Asynchronous</emphasis>, device event processing continues + normally. If the device is currently frozen by this client, then processing + of device events is resumed. If this-device-mode is <emphasis>Synchronous</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 other-device-mode is <emphasis>Asynchronous</emphasis>, event processing is + unaffected by activation of the grab. If other-device-mode is + <emphasis>Synchronous</emphasis>, the state of all input devices except the grabbed one + (as seen by means of the protocol) appears to + freeze, and no further events are generated by the server until + the grabbing client issues a releasing <emphasis>AllowDeviceEvents</emphasis> 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.</para> + <para>This request generates <emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events.</para> + <para>This request fails and returns:</para> + <variablelist remap='IP'> + <varlistentry> + <term><constant>AlreadyGrabbed</constant></term> + <listitem><para>If the device is actively grabbed by some + other client.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>NotViewable</constant></term> + <listitem> + <para> If grab-window is not viewable.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><constant>InvalidTime</constant></term> + <listitem> + <para> + 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> + </varlistentry> + <varlistentry> + <term><constant>Frozen</constant></term> + <listitem> + <para>If the device is frozen by an active grab of another client.</para> + </listitem> + </varlistentry> + </variablelist> + <para>If a grabbed device is closed by a client while an active grab by that + client is in + effect, that active grab will be released. Any passive grabs established by + that client will be released. If the device is frozen only by an active grab + of the requesting client, it is thawed.</para> + <para>To release a grab of an extension device, use <emphasis>UngrabDevice</emphasis>. + <literallayout> + UngrabDevice + device: DEVICE + time: TIMESTAMP or CurrentTime + </literallayout> + Errors: Device</para> + + <para>This request releases the device if this client has it actively grabbed + (from either <emphasis>GrabDevice</emphasis> or <emphasis>GrabDeviceKey</emphasis>) and releases + any queued events. If any devices were frozen by the grab, + <emphasis>UngrabDevice</emphasis> thaws them. + The request has no effect if the specified time is earlier + than the last-device-grab time or is later than the current server time.</para> + <para>This request generates <emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events.</para> + <para>An <emphasis>UngrabDevice</emphasis> is performed automatically if the event window for an + active device grab becomes not viewable.</para> + </sect2> + <sect2 id='passively_grabbing_a_key'><title>Passively Grabbing A Key</title> + <para>Passive grabs of buttons and keys on extension devices are supported + via the <emphasis>GrabDeviceButton</emphasis> and <emphasis>GrabDeviceKey</emphasis> requests. + These passive grabs are released via the <emphasis>UngrabDeviceKey</emphasis> and + <emphasis>UngrabDeviceButton</emphasis> requests.</para> + <para>To passively grab a single key on an extension device, use <emphasis>GrabDeviceKey</emphasis>. + That device must have previously been opened using the <emphasis>OpenDevice</emphasis> + request. + <literallayout> + GrabDeviceKey + device: DEVICE + keycode: KEYCODE or AnyKey + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} + </literallayout> + </para> + <para>Errors: Device, Match, Access, Window, Value</para> + <para>This request is analogous to the core <emphasis>GrabKey</emphasis> request. It establishes a + passive grab on a device. Consequently, in the future: + <itemizedlist> + <listitem> + <para>IF the device is not grabbed and the specified key, which itself can be a + modifier key, is logically pressed when the specified modifier keys + logically are down on the specified modifier device (and no other + keys are down),</para> + </listitem> + <listitem> + <para>AND no other modifier keys logically are down,</para> + </listitem> + <listitem> + <para>AND EITHER the grab window is an ancestor of (or is) the focus window + OR the grab window is a descendent of the focus window and contains the pointer,</para> + </listitem> + <listitem> + <para>AND a passive grab on the same device and key combination does not exist on any + ancestor of the grab window,</para> + </listitem> + <listitem> + <para>THEN the device is actively grabbed, as for <emphasis>GrabDevice</emphasis>, + the last-device-grab time is set to the time at which the key was pressed + (as transmitted in the <emphasis>DeviceKeyPress</emphasis> event), and the + <emphasis>DeviceKeyPress</emphasis> event is reported.</para> + </listitem> + </itemizedlist> + </para> + <para>The interpretation of the remaining arguments is as for <emphasis>GrabDevice</emphasis>. + The active grab is terminated automatically when logical state of the + device has the specified key released (independent of the logical state of the + modifier keys).</para> + <para>Note that the logical state of a device (as seen by means of the X protocol) + may lag the physical state if device event processing is frozen.</para> + <para>A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the request for all + possible modifier combinations (including the combination of no modifiers). + It is not required that all modifiers specified have currently assigned + keycodes. + A key of <emphasis>AnyKey</emphasis> is equivalent to issuing + the request for all possible keycodes. Otherwise, the key must be in + the range specified by min-keycode and max-keycode in the <emphasis>ListInputDevices</emphasis> + request. If it is not within that range, <emphasis>GrabDeviceKey</emphasis> generates a + <emphasis>Value</emphasis> error.</para> + <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is + <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> + <para>An <emphasis>Access</emphasis> error is generated if some other client has issued a + <emphasis>GrabDeviceKey</emphasis> with the same device and key combination on the + same window. When using <emphasis>AnyModifier</emphasis> or <emphasis>AnyKey</emphasis>, + the request fails completely and the X server generates a <emphasis>Access</emphasis> + error and no grabs are established if there is a conflicting grab for any + combination.</para> + <para>This request cannot be used to grab a key on the X keyboard device. + The core <emphasis>GrabKey</emphasis> request should be used for that purpose.</para> + <para>To release a passive grab of a single key on an extension device, + use <emphasis>UngrabDeviceKey</emphasis>. + <literallayout> + UngrabDeviceKey + device: DEVICE + keycode: KEYCODE or AnyKey + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + </literallayout> + Errors: Device, Match, Window, Value, Alloc</para> + <para>This request is analogous to the core <emphasis>UngrabKey</emphasis> request. It releases + the key combination on the specified window if it was grabbed by this + client. A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the + request for all possible modifier combinations (including the combination + of no modifiers). A key of <emphasis>AnyKey</emphasis> is equivalent to issuing the + request for all possible keycodes. This request has no effect on an + active grab.</para> + <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is + <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> + </sect2> + <sect2 id='passively_grabbing_a_button'><title>Passively Grabbing A Button</title> + <para>To establish a passive grab for a single button on an extension device, + use <emphasis>GrabDeviceButton</emphasis>. + <literallayout> + GrabDeviceButton + device: DEVICE + button: BUTTON or AnyButton + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + owner-events: BOOL + event-list: LISTofEVENTCLASS + this-device-mode: {Synchronous, Asynchronous} + other-device-mode: {Synchronous, Asynchronous} + </literallayout> + Errors: Device, Match, Window, Access, Value</para> + <para>This request is analogous to the core <emphasis>GrabButton</emphasis> request. It + establishes an explicit passive grab for a button on an extension input + device. Since the server does not track extension devices, no cursor is + specified with this request. For the same reason, there is no + confine-to parameter. The device must have previously been opened using the + <emphasis>OpenDevice</emphasis> request.</para> + <para>The <emphasis>GrabDeviceButton</emphasis> request establishes a passive grab on a device. + Consequently, in the future,</para> + <variablelist remap='IP'> + <varlistentry> + <term>•</term> + <listitem> + <para>IF the device is not grabbed and the specified button is logically pressed + when the specified modifier keys logically are down + (and no other buttons or modifier keys are down),</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>AND the grab window contains the device,</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>AND a passive grab on the same device and button/ key combination does not + exist on any ancestor of the grab window,</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>THEN the device is actively grabbed, as for <emphasis>GrabDevice</emphasis>, + the last-grab time is set to the time at which the button was pressed + (as transmitted in the <emphasis>DeviceButtonPress</emphasis> event), and the + <emphasis>DeviceButtonPress</emphasis> event is reported.</para> + </listitem> + </varlistentry> + </variablelist> + <para>The interpretation of the remaining arguments is as for + <emphasis>GrabDevice</emphasis>. + The active grab is terminated automatically when logical state of the + device has all buttons released (independent of the logical state of + the modifier keys).</para> + <para>Note that the logical state of a device (as seen by means of the X protocol) + may lag the physical state if device event processing is frozen.</para> + <para>A modifier of <emphasis>AnyModifier</emphasis> is equivalent to issuing the request for all + possible modifier combinations (including the combination of no modifiers). + It is not required that all modifiers specified have currently assigned + keycodes. A button of <emphasis>AnyButton</emphasis> is equivalent to issuing the request + for all possible buttons. It is not required that the + specified button be assigned to a physical button.</para> + <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is + <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> + <para>An <emphasis>Access</emphasis> error is generated if some other client has issued a + <emphasis>GrabDeviceButton</emphasis> with the same device and button combination on the + same window. When using <emphasis>AnyModifier</emphasis> or <emphasis>AnyButton</emphasis>, the request + fails completely and the X server generates a <emphasis>Access</emphasis> + error and no grabs are established if there is a conflicting grab for any + combination. The request has no effect on an active grab.</para> + <para>This request cannot be used to grab a button on the X pointer + device. The core <emphasis>GrabButton</emphasis> request should be used for that + purpose.</para> + <para>To release a passive grab of a button on an extension device, use + <emphasis>UngrabDeviceButton</emphasis>. + <literallayout> + UngrabDeviceButton + device: DEVICE + button: BUTTON or AnyButton + modifiers: SETofKEYMASK or AnyModifier + modifier-device: DEVICE or NULL + grab-window: WINDOW + </literallayout> + Errors: Device, Match, Window, Value, Alloc</para> + <para>This request is analogous to the core UngrabButton request. It releases + the passive button/key combination on the specified window if it was grabbed + by the client. A modifiers of <emphasis>AnyModifier</emphasis> is equivalent to issuing the + request for all possible modifier combinations (including the combination + of no modifiers). A button of <emphasis>AnyButton</emphasis> is equivalent to issuing the + request for all possible buttons. This request has no effect on an + active grab. The device must have previously been opened using the + <emphasis>OpenDevice</emphasis> request otherwise a <emphasis>Device</emphasis> error will be + generated.</para> + <para><emphasis>NULL</emphasis> may be passed for the modifier_device. If the modifier_device is + <emphasis>NULL</emphasis>, the core X keyboard is used as the modifier_device.</para> + <para>This request cannot be used to ungrab a button on the X pointer + device. The core <emphasis>UngrabButton</emphasis> request should be used for that + purpose.</para> + </sect2> + <sect2 id='thawing_a_device'><title>Thawing A Device</title> + <para>To allow further events to be processed when a device has been frozen, + use <emphasis>AllowDeviceEvents</emphasis>. + <literallayout> + AllowDeviceEvents + device: DEVICE + event-mode: {AsyncThisDevice, SyncThisDevice, AsyncOtherDevices, + ReplayThisdevice, AsyncAll, or SyncAll} + time:TIMESTAMP or CurrentTime + </literallayout> + Errors: Device, Value</para> + <para>The <emphasis>AllowDeviceEvents</emphasis> request releases some queued events if the client + has caused a device to freeze. The request has no effect if the + specified time is earlier than the last-grab time of the most recent + active grab for the client, or if the specified time is later than the + current X server time.</para> + <para>The following describes the processing that occurs depending on what constant + you pass to the event-mode argument:</para> + <variablelist remap='IP'> + <varlistentry> + <term>•</term> + <listitem> + <para>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 client on + behalf of multiple separate grabs, AsyncThisDevice thaws for all. + AsyncThisDevice has no effect if the specified device is not frozen by the + client, but the device need not be grabbed by the client.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If the specified device is frozen and actively grabbed by the client, + event processing for that device continues normally until the next + button or key event is reported to the client. + At this time, + the specified device again appears to freeze. + However, if the reported event causes the grab to be released, + the specified device does not freeze. + SyncThisDevice has no effect if the specified device is not frozen by the client + or is not grabbed by the client.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If the specified device is actively grabbed by the client and is frozen + as the result of an event having been sent to the client (either from the + activation of a GrabDeviceButton or from a previous AllowDeviceEvents with + mode SyncThisDevice, but not from a Grab), + the grab is released and that event is completely reprocessed. + This time, however, the request ignores any passive grabs at or above + (towards the root) the grab-window of the grab just released. + The request has no effect if the specified device is not grabbed by the client + or if it is not frozen as the result of an event.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If the remaining devices are frozen by the client, + event processing for them continues as usual. + If the other devices are frozen multiple times by the client on behalf of + multiple separate grabs, + AsyncOtherDevices “thaws” for all. + AsyncOtherDevices has no effect if the devices are not frozen by the client, + but those devices need not be grabbed by the client.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If all devices are frozen by the client, + event processing (for all devices) continues normally until the next + button or key event is reported + to the client for a grabbed device (button event for the grabbed device, key + or motion event for the device), at which time the devices again appear to + freeze. However, if the reported event causes the grab to be released, + then the devices do not freeze (but if any device is still + grabbed, then a subsequent event for it will still cause all devices + to freeze). + SyncAll has no effect unless all devices + are frozen by the client. If any device is frozen twice + by the client on behalf of two separate grabs, + SyncAll "thaws" for both (but a subsequent freeze for SyncAll + will only freeze each device once).</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If all devices are frozen by the + client, event processing (for all devices) continues normally. + If any device is frozen multiple times by the client on behalf of multiple + separate grabs, AsyncAll "thaws" for all. + AsyncAll has no effect unless all + devices are frozen by the client.</para> + <para>AsyncThisDevice, SyncThisDevice, and ReplayThisDevice + have no effect on the processing of events from the remaining devices. + AsyncOtherDevices has no effect on the processing of events from the + specified device. + When the event_mode is SyncAll or AsyncAll, the + device parameter is ignored.</para> + <para>It is possible for several grabs of different devices (by the same + or different clients) to be active simultaneously. + If a device is frozen on behalf of any grab, + no event processing is performed for the device. + It is possible for a single device to be frozen because of several grabs. + In this case, + the freeze must be released on behalf of each grab before events can + again be processed.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2 id='controlling_device_focus'><title>Controlling Device Focus</title> + <para>The current focus window for an extension input device can be + determined using the <emphasis>GetDeviceFocus</emphasis> request. + Extension devices are focused using the <emphasis>SetDeviceFocus</emphasis> + request in the same way that the keyboard is focused using + the <emphasis>SetInputFocus</emphasis> request, except that a device is specified as + part of the request. One additional focus state, <emphasis>FollowKeyboard</emphasis>, + is provided for extension devices.</para> + <para>To get the current focus state, revert state, and focus time of an extension device, + use <emphasis>GetDeviceFocus</emphasis>. + <literallayout> + GetDeviceFocus + device: DEVICE + => + focus: WINDOW, PointerRoot, FollowKeyboard, or None + revert-to: Parent, PointerRoot, FollowKeyboard, or None + focus-time: TIMESTAMP + </literallayout> + Errors: Device, Match</para> + <para>This request returns the current focus state, revert-to state, + and last-focus-time of an extension device.</para> + <para>To set the focus of an extension device, use <emphasis>SetDeviceFocus</emphasis>. + <literallayout> + SetDeviceFocus + device: DEVICE + focus: WINDOW, PointerRoot, FollowKeyboard, or None + revert-to: Parent, PointerRoot, FollowKeyboard, or None + focus-time: TIMESTAMP + </literallayout> + Errors: Device, Window, Value, Match</para> + <para>This request changes the focus for an extension input device and the + last-focus-change-time. The request has no effect if the specified + time is earlier than the last-focus-change-time or is later than the + current X server time. Otherwise, the last-focus-change-time is set to the + specified time, with CurrentTime replaced by the current server time.</para> + <para>The action taken by the server when this request is requested depends + on the value of the focus argument:</para> + <variablelist remap='IP'> + <varlistentry> + <term>•</term> + <listitem> + <para>If the focus argument is <emphasis>None</emphasis>, all input events from this device + will be discarded until a new focus window is set. In this case, the + revert-to argument is ignored.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If a window ID is assigned to the focus argument, it becomes the focus + window of the device. If an input event from the device would normally + be reported to this window or to one of its inferiors, the event is + reported normally. Otherwise, the event is reported relative to the focus + window.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If you assign <emphasis>PointerRoot</emphasis> to the focus argument, the focus window is + dynamically taken to be the root window of whatever screen the pointer is + on at each input event. In this case, the revert-to argument is ignored.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If you assign <emphasis>FollowKeyboard</emphasis> to the focus argument, the focus window is + dynamically taken to be the same as the focus of the X keyboard at each + input event.</para> + <para>The specified focus window must be viewable at the time of the request + (else a <emphasis>Match</emphasis> error). If the focus window later becomes not viewable, + the X server evaluates the revert-to argument + to determine the new focus window.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If you assign <emphasis>RevertToParent</emphasis> + to the revert-to argument, the focus reverts to the parent + (or the closest viewable ancestor), and the new revert-to value is taken to + be <emphasis>RevertToNone</emphasis>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>•</term> + <listitem> + <para>If you assign <emphasis>RevertToPointerRoot</emphasis>, + <emphasis>RevertToFollowKeyboard</emphasis>, or + <emphasis>RevertToNone</emphasis> to the revert-to + argument, the focus reverts to that value.</para> + </listitem> + </varlistentry> + </variablelist> + <para>When the focus reverts, + the X server generates <emphasis>DeviceFocusIn</emphasis> + and <emphasis>DeviceFocusOut</emphasis> + events, but the last-focus-change time is not affected.</para> + <para>This request causes the X server to generate <emphasis>DeviceFocusIn</emphasis> and + <emphasis>DeviceFocusOut</emphasis> events.</para> + </sect2> + <sect2 id='controlling_device_feedback'><title>Controlling Device Feedback</title> + <para>To get the settings of feedbacks on an extension device, use + <emphasis>GetFeedbackControl</emphasis>. This request provides functionality equivalent to + the core <emphasis>GetKeyboardControl</emphasis> and <emphasis>GetPointerControl</emphasis> functions. It + also provides a way to control displays associated with an input device that + are capable of displaying an integer or string. + <literallayout> + GetFeedbackControl + device: DEVICE + => + num_feedbacks_return: CARD16 + return_value: LISTofFEEDBACKSTATE + </literallayout> + where + <literallayout> + FEEDBACKSTATE: {KbdFeedbackState, PtrFeedbackState, + IntegerFeedbackState, StringFeedbackState, + BellFeedbackState, LedFeedbackState} + </literallayout> + </para> + <para>Feedbacks are reported by class. Those + feedbacks that are reported for the core keyboard device are in class + <emphasis>KbdFeedback</emphasis>, and are returned in the + <emphasis>KbdFeedbackState</emphasis> structure. The members of that structure are as follows: + <literallayout> + CLASS Kbd: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + key_click_percent: CARD8 + bell_percent: CARD8 + bell_pitch: CARD16 + bell_duration: CARD16 + led_value: BITMASK + global_auto_repeat: {AutoRepeatModeOn, AutoRepeatModeOff} + auto_repeats: LISTofCARD8] + </literallayout> + </para> + <para>Those feedbacks that are equivalent to those reported for the core pointer + are in feedback class <emphasis>PtrFeedback</emphasis> and are reported in the + <emphasis>PtrFeedbackState</emphasis> structure. The members of that structure are: + <literallayout> + CLASS Ptr: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + accelNumerator: CARD16 + accelDenominator: CARD16 + threshold: CARD16] + </literallayout> + </para> + <para>Some input devices provide a means of displaying an integer. Those devices + will support feedback class <emphasis>IntegerFeedback</emphasis>, which is reported in the + <emphasis>IntegerFeedbackState</emphasis> structure. The members of that structure are: + <literallayout> + CLASS Integer: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + resolution: CARD32 + min-val: INT32 + max-val: INT32] + </literallayout> + </para> + <para>Some input devices provide a means of displaying a string. Those devices + will support feedback class <emphasis>StringFeedback</emphasis>, which is reported in the + <emphasis>StringFeedbackState</emphasis> structure. The members of that structure are: + <literallayout> + CLASS String: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + max_symbols: CARD16 + num_keysyms_supported: CARD16 + keysyms_supported: LISTofKEYSYM] + </literallayout> + </para> + <para>Some input devices contain a bell. Those devices + will support feedback class <emphasis>BellFeedback</emphasis>, which is reported in the + <emphasis>BellFeedbackState</emphasis> structure. The members of that structure are: + <literallayout> + CLASS String: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + percent: CARD8 + pitch: CARD16 + duration: CARD16] + </literallayout> + </para> + <para>The percent sets the base volume for the bell between 0 (off) and 100 + (loud) inclusive, if possible. Setting to -1 restores the default. + Other negative values generate a <emphasis>Value</emphasis> error.</para> + <para>The pitch sets the pitch (specified in Hz) of the bell, if possible. + Setting to -1 restores the default. Other negative values generate a + <emphasis>Value</emphasis> error.</para> + <para>The duration sets the duration (specified in milliseconds) of the + bell, if possible. Setting to -1 restores the default. + Other negative values generate a <emphasis>Value</emphasis> error.</para> + <para>A bell generator connected with the console but not directly on the + device is treated as if it were part of the device. + Some input devices contain LEDs. Those devices + will support feedback class <emphasis>Led</emphasis>, which is reported in the + <emphasis>LedFeedbackState</emphasis> structure. The members of that structure are: + <literallayout> + CLASS String: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + led_mask: BITMASK + led_value: BITMASK] + </literallayout> + </para> + <para>Each bit in led_mask indicates that the corresponding led is supported by + the feedback. At most 32 LEDs per feedback are supported. + No standard interpretation of LEDs is defined.</para> + <para>This function will fail with a <emphasis>BadMatch</emphasis> error if the device specified + in the request does not support feedbacks.</para> + <para>Errors: Device, Match</para> + <para>To change the settings of a feedback on an extension device, use + <emphasis>ChangeFeedbackControl</emphasis>. + <literallayout> + ChangeFeedbackControl + device: DEVICE + feedbackid: CARD8 + value-mask: BITMASK + value: FEEDBACKCONTROL + + FEEDBACKCONTROL: {KBDFEEDBACKCONTROL, + PTRFEEDBACKCONTROL, + INTEGERFEEDBACKCONTROL, + STRINGFEEDBACKCONTROL, + BELLFEEDBACKCONTROL, + LEDFEEDBACKCONTROL} + </literallayout> + Errors: Device, Match, Value</para> + <para>Feedback controls are grouped by class. Those feedbacks that are + equivalent to those supported by the core keyboard are controlled + by feedback class <emphasis>KbdFeedbackClass</emphasis> using the <emphasis>KbdFeedbackControl</emphasis> + structure. The members of that structure are: + <literallayout> + KBDFEEDBACKCTL + [class: CARD8 + length: CARD16 + feedback id: CARD8 + key_click_percent: INT8 + bell_percent: INT8 + bell_pitch: INT16 + bell_duration: INT16 + led_mask: INT32 + led_value: INT32 + key: KEYCODE + auto_repeat_mode: {AutoRepeatModeOn, AutoRepeatModeOff, + AutoRepeatModeDefault}] + </literallayout> + </para> + <para>The key_click_percent sets the volume for key clicks between 0 (off) and + 100 (loud) inclusive, if possible. Setting to -1 restores the default. + Other negative values generate a <emphasis>Value</emphasis> error.</para> + <para>If both auto_repeat_mode and key are specified, then the auto_repeat_mode + of that key is changed, if possible. If only auto_repeat_mode is specified, + then the global auto-repeat mode for the entire keyboard is changed, + if possible, without affecting the per-key settings. It is a <emphasis>Match</emphasis> + error if a key is specified without an auto_repeat_mode.</para> + <para>The order in which controls are verified and altered is server-dependent. + If an error is generated, a subset of the controls may have been altered.</para> + <para>Those feedback controls equivalent to those of the core pointer are + controlled by feedback class <emphasis>PtrFeedbackClass</emphasis> using the + <emphasis>PtrFeedbackControl</emphasis> + structure. The members of that structure are as follows: + <literallayout> + PTRFEEDBACKCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + accelNumerator: INT16 + accelDenominator: INT16 + threshold: INT16] + </literallayout> + </para> + <para>The acceleration, expressed as a fraction, is a multiplier + for movement. For example, specifying 3/1 means the device moves three + times as fast as normal. The fraction may be rounded arbitrarily by the + X server. Acceleration only takes effect if the device moves more than + threshold pixels at once and only applies to the amount beyond the value + in the threshold argument. Setting a value to -1 restores the default. + The values of the do-accel and do-threshold arguments must be nonzero for + the device values to be set. Otherwise, the parameters will be unchanged. + Negative values generate a <emphasis>Value</emphasis> error, as does a zero value + for the accel-denominator argument.</para> + <para>Some devices are capable of displaying an integer. This is done using + feedback class <emphasis>IntegerFeedbackClass</emphasis> using the <emphasis>IntegerFeedbackControl</emphasis> + structure. The members of that structure are as follows: + <literallayout> + INTEGERCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + int_to_display: INT32] + </literallayout> + </para> + <para>Some devices are capable of displaying an string. This is done using + feedback class <emphasis>StringFeedbackClass</emphasis> using the <emphasis>StringFeedbackCtl</emphasis> + structure. The members of that structure are as follows: + <literallayout> + STRINGCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + syms_to_display: LISTofKEYSYMS] + </literallayout> + </para> + <para>Some devices contain a bell. This is done using + feedback class <emphasis>BellFeedbackClass</emphasis> using the <emphasis>BellFeedbackControl</emphasis> + structure. The members of that structure are as follows: + <literallayout> + BELLCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + percent: INT8 + pitch: INT16 + duration: INT16] + </literallayout> + </para> + <para>Some devices contain leds. These can be turned on and off using + the <emphasis>LedFeedbackControl</emphasis> + structure. The members of that structure are as follows: + <literallayout> + LEDCTL: + [class: CARD8 + length: CARD16 + feedback id: CARD8 + led_mask: BITMASK + led_value: BITMASK] + </literallayout> + Errors: Device, Match, Value</para> + </sect2> + <sect2 id='ringing_a_bell_on_an_input_device'><title>Ringing a Bell on an Input Device</title> + <para>To ring a bell on an extension input device, use <emphasis>DeviceBell</emphasis>. + <literallayout> + DeviceBell: + device: DEVICE + feedbackclass: CARD8 + feedbackid: CARD8 + percent: INT8 + </literallayout> + Errors: Device, Value</para> + <para>This request is analogous to the core <emphasis>Bell</emphasis> request. It rings the + specified bell on the specified input device feedback, using the specified + volume. + The specified volume is relative to the base volume for the feedback. + If the value for the percent argument is not in the range -100 to 100 + inclusive, a <emphasis>Value</emphasis> error results. + The volume at which the bell rings when the percent argument is nonnegative is:</para> + <literallayout remap='DS'> + base - [(base * percent) / 100] + percent + </literallayout> + <para>The volume at which the bell rings + when the percent argument is negative is:</para> + <literallayout remap='DS'> + base + [(base * percent) / 100] + </literallayout> + <para>To change the base volume of the bell, use <emphasis>ChangeFeedbackControl</emphasis> request.</para> + </sect2> + <sect2 id='controlling_device_encoding'><title>Controlling Device Encoding</title> + <para>To get the keyboard mapping of an extension device that has keys, use + <emphasis>GetDeviceKeyMapping</emphasis>. + <literallayout> + GetDeviceKeyMapping + device: DEVICE + first-keycode: KEYCODE + count: CARD8 + => + keysyms-per-keycode: CARD8 + keysyms: LISTofKEYSYM + </literallayout> + Errors: Device, Match, Value</para> + <para>This request returns the symbols for the specified number of keycodes for the + specified extension device, starting with the specified keycode. + The first-keycode must be greater than or equal to + min-keycode as returned in the connection setup (else a <emphasis>Value</emphasis> error), + and</para> + <literallayout remap='DS'> + first-keycode + count - 1 + </literallayout> + <para>must be less than or equal to max-keycode as returned in the connection setup + (else a <emphasis>Value</emphasis> error). + The number of elements in the keysyms list is</para> + <literallayout remap='DS'> + count * keysyms-per-keycode + </literallayout> + <para>and KEYSYM number N (counting from zero) for keycode K has an index + (counting from zero) of</para> + <literallayout remap='DS'> + (K - first-keycode) * keysyms-per-keycode + N + </literallayout> + <para>in keysyms. + The keysyms-per-keycode value is chosen arbitrarily by the server + to be large enough to report all requested symbols. + A special KEYSYM value of + <emphasis>NoSymbol</emphasis> + is used to fill in unused elements for individual keycodes.</para> + <para>If the specified device has not first been opened by this client via + <emphasis>OpenDevice</emphasis>, or if that device does not support input class Keys, + this request will fail with a <emphasis>Device</emphasis> error.</para> + <para>To change the keyboard mapping of an extension device that has keys, use + <emphasis>ChangeDeviceKeyMapping</emphasis>. + <literallayout> + ChangeDeviceKeyMapping + device: DEVICE + first-keycode: KEYCODE + keysyms-per-keycode: CARD8 + keysyms: LISTofKEYSYM + num_codes: CARD8 + </literallayout> + Errors: Device, Match, Value, Alloc</para> + <para>This request is analogous to the core <emphasis>ChangeKeyMapping</emphasis> request. + It defines the symbols for the specified number of keycodes for the + specified extension device. + If the specified device has not first been opened by this client via + <emphasis>OpenDevice</emphasis>, or if that device does not support input class Keys, + this request will fail with a <emphasis>Device</emphasis> error.</para> + <para>The number of elements in the keysyms list must be a multiple of + keysyms_per_keycode. Otherwise, <emphasis>ChangeDeviceKeyMapping</emphasis> generates + a <emphasis>Length</emphasis> error. The specified first_keycode must be greater + than or equal to the min_keycode value returned by the <emphasis>ListInputDevices</emphasis> + request, or this request will fail with a <emphasis>Value</emphasis> error. In addition, + if the following expression is not less than the max_keycode value returned by + the <emphasis>ListInputDevices</emphasis> request, the request will fail with a <emphasis>Value</emphasis> + error:</para> + <literallayout remap='DS'> + first_keycode + (num_codes / keysyms_per_keycode) - 1 + </literallayout> <!-- remap='DE' --> + <para>To obtain the keycodes that are used as modifiers on an + extension device that has keys, use <emphasis>GetDeviceModifierMapping</emphasis>. + <literallayout> + GetDeviceModifierMapping + device: DEVICE + => + keycodes-per-modifier: CARD8 + keycodes: LISTofKEYCODE + </literallayout> + Errors: Device, Match</para> + <para>This request is analogous to the core <emphasis>GetModifierMapping</emphasis> request. + This request returns the keycodes of the keys being used as modifiers. + The number of keycodes in the list is 8*keycodes-per-modifier. + The keycodes are divided into eight sets, with each set containing + keycodes-per-modifier elements. The sets are assigned in order to the + modifiers <emphasis>Shift</emphasis>, + <emphasis>Lock</emphasis>, <emphasis>Control</emphasis>, + <emphasis>Mod1</emphasis>, <emphasis>Mod2</emphasis>, + <emphasis>Mod3</emphasis>, <emphasis>Mod4</emphasis>, and + <emphasis>Mod5</emphasis>. The keycodes-per-modifier value is + chosen arbitrarily by the server; zeroes are used to fill in unused elements + within each set. If only zero values are given in a set, the use of the + corresponding modifier has been disabled. The order of keycodes within + each set is chosen arbitrarily by the server.</para> + <para>To set which keycodes that are to be used as modifiers for an extension + device, use <emphasis>SetDeviceModifierMapping</emphasis>. + <literallayout> + SetDeviceModifierMapping + device: DEVICE + keycodes-per-modifier: CARD8 + keycodes: LISTofKEYCODE + => + status: {Success, Busy, Failed} + </literallayout> + Errors: Device, Match, Value, Alloc</para> + <para>This request is analogous to the core <emphasis>SetModifierMapping</emphasis> request. + This request specifies the keycodes (if any) of the keys to be used as + modifiers. The number of keycodes in the list must be + 8*keycodes-per-modifier (else a <emphasis>Length</emphasis> error). The keycodes are + divided into eight sets, with the sets, with each set containing + keycodes-per-modifier elements. The sets are assigned in order to the + modifiers <emphasis>Shift</emphasis>, + <emphasis>Lock</emphasis>, <emphasis>Control</emphasis>, + <emphasis>Mod1</emphasis>, <emphasis>Mod2</emphasis>, + <emphasis>Mod3</emphasis>, <emphasis>Mod4</emphasis>, and + <emphasis>Mod5</emphasis>. Only non-zero keycode values are + used within each set; zero values are ignored. All of the non-zero + keycodes must be in the range specified by min-keycode and max-keycode + in the <emphasis>ListInputDevices</emphasis> request (else a <emphasis>Value</emphasis> error). The order of + keycodes within a set does not matter. If no non-zero values are specified + in a set, the use of the corresponding modifier is disabled, and the + modifier bit will always be zero. Otherwise, the modifier bit will be + one whenever at least one of the keys in the corresponding set is in the down + position.</para> + <para>A server can impose restrictions on how modifiers can be changed (for example, + if certain keys do not generate up transitions in hardware or if multiple keys + per modifier are not supported). The status reply is <emphasis>Failed</emphasis> + if some such restriction is violated, and none of the modifiers are changed.</para> + <para>If the new non-zero keycodes specified for a modifier differ from those + currently defined, and any (current or new) keys for that modifier are + logically in the down state, then the status reply is <emphasis>Busy</emphasis>, + and none of the modifiers are changed.</para> + <para>This request generates a <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event on a + <emphasis>Success</emphasis> status. The <emphasis remap='P->B'>DeviceMappingNotify</emphasis> event will be sent only + to those clients that have expressed an interest in receiving that event + via the <emphasis>XSelectExtensionEvent</emphasis> request.</para> + <para>A X server can impose restrictions on how modifiers can be changed, + for example, if certain keys do not generate up transitions in hardware + or if multiple modifier keys are not supported. If some such restriction + is violated, the status reply is + <emphasis>MappingFailed</emphasis> , and none of the modifiers are changed. + If the new keycodes specified for a modifier differ from those + currently defined and any (current or new) keys for that modifier are + in the logically down state, the status reply is <emphasis>MappingBusy</emphasis>, + and none of the modifiers are changed.</para> + </sect2> + <sect2 id='controlling_button_mapping'><title>Controlling Button Mapping</title> + <para>These requests are analogous to the core <emphasis>GetPointerMapping</emphasis> + and <emphasis>ChangePointerMapping</emphasis> requests. They allow a client to + determine the current mapping of buttons on an extension device, + and to change that mapping.</para> + <para>To get the current button mapping for an extension device, use + <emphasis>GetDeviceButtonMapping</emphasis>. + <literallayout> + GetDeviceButtonMapping + device: DEVICE + nmap: CARD8 + => + map_return: LISTofCARD8 + </literallayout> + Errors: Device, Match</para> + <para>The <emphasis>GetDeviceButtonMapping</emphasis> function returns the current mapping of + the buttons on the specified device. Elements of the list are indexed + starting from one. The length of the list indicates the number of + physical buttons. The nominal mapping is the identity mapping map[i]=i.</para> + <para><emphasis>nmap</emphasis> indicates the number of elements in the <emphasis>map_return</emphasis> + array. Only the first nmap entries will be copied by the library + into the map_return array.</para> + <para>To set the button mapping for an extension device, use + <emphasis>SetDeviceButtonMapping</emphasis>. + <literallayout> + SetDeviceButtonMapping + device: DEVICE + map: LISTofCARD8 + nmap: CARD8 + => + status: CARD8 + </literallayout> + Errors: Device, Match, Value</para> + <para>The <emphasis>SetDeviceButtonMapping</emphasis> function sets the mapping of the specified + device and causes the X server to generate a <emphasis>DeviceMappingNotify</emphasis> + event on a status of <emphasis>MappingSuccess</emphasis>. Elements of the list are + indexed starting from one. The length of the list, + specified in <emphasis>nmap</emphasis>, + must be the same as + <emphasis>GetDeviceButtonMapping</emphasis> would return. Otherwise, + <emphasis>SetDeviceButtonMapping</emphasis> generates a <emphasis>Value</emphasis> error. A zero element + disables a buttons, and elements are not restricted in value by the + number of physical buttons. However, no two elements can have the + same nonzero value. Otherwise, this function generates a + <emphasis>Value</emphasis> error. If any of the buttons to be altered are in the + down state, the status reply is <emphasis>MappingBusy</emphasis> and the mapping is + not changed.</para> + </sect2> + <sect2 id='obtaining_the_state_of_a_device'><title>Obtaining The State Of A Device</title> + <para>To obtain vectors that describe the state of the keys, buttons and valuators + of an extension device, use <emphasis>QueryDeviceState</emphasis>. + <literallayout> + QueryDeviceState + device: DEVICE + => + device-id: CARD8 + data: LISTofINPUTCLASS + </literallayout> + where + <literallayout> + INPUTCLASS: {VALUATOR, BUTTON, KEY} + + CLASS VALUATOR: + [class: CARD8 + num_valuators: CARD8 + mode: CARD8 + #x01 device mode (0 = Relative, 1 = Absolute) + #x02 proximity state (0 = InProximity, 1 = OutOfProximity) + valuators: LISTofINT32] + + CLASS BUTTON: + [class: CARD8 + num_buttons: CARD8 + buttons: LISTofCARD8] + + CLASS KEY: + [class: CARD8 + num_keys: CARD8 + keys: LISTofCARD8] + </literallayout> + Errors: Device</para> + <para>The <emphasis>QueryDeviceState</emphasis> request returns the current logical state of the + buttons, keys, and valuators on the specified input device. + The <emphasis remap='I'>buttons</emphasis> and <emphasis remap='I'>keys</emphasis> arrays, byte N (from 0) contains the + bits for key or button 8N to 8N+7 with the least significant bit in the + byte representing key or button 8N.</para> + <para>If the device has valuators, a bit in the mode field indicates whether the + device is reporting Absolute or Relative data. If it is reporting Absolute + data, the valuators array will contain the current value of the valuators. + If it is reporting Relative data, the valuators array will contain undefined + data.</para> + <para>If the device reports proximity information, a bit in the mode field indicates + whether the device is InProximity or OutOfProximity.</para> + </sect2> + </sect1> + <sect1 id='events'><title>Events</title> + <para>The input extension creates input events analogous to the core input events. + These extension input events are generated by manipulating one of the + extension input devices.</para> + <sect2 id='button_key_and_motion_events'><title>Button, Key, and Motion Events</title> + <para> + <literallayout> + DeviceKeyPress + DeviceKeyRelease + DeviceButtonPress, + DeviceButtonRelease + DeviceMotionNotify + device: CARD8 + root, event: WINDOW + child: Window or None + same-screen: BOOL + root-x, root-y, event-x, event-y: INT16 + detail: <see below> + state: SETofKEYBUTMASK + time: TIMESTAMP + </literallayout> + </para> + <para>These events are generated when a key, button, or valuator logically changes state. + The generation of these logical changes may lag the physical changes, + if device event processing is frozen. Note that <emphasis>DeviceKeyPress</emphasis> + and <emphasis>DeviceKeyRelease</emphasis> are generated for all keys, even those mapped to modifier bits. + The “source” of the event is the window the pointer is in. + The window with respect to which the event is normally reported is found + by looking up the hierarchy (starting with the source window) + for the first window on which any client has selected interest in the event. + The actual window used for reporting can be modified by active grabs and + by the focus window.The window the event is reported with respect to is called + the “event” window.</para> + <para>The root is the root window of the “source” window, and root-x and root-y + are the pointer coordinates relative to root's origin at the time of the event. + Event is the “event” window. If the event window is on the same screen as + root, then event-x and event-y are the pointer coordinates relative to the + event window's origin. Otherwise, event-x and event-y are zero. If the + source window is an inferior of the event window, then child is set to + the child of the event window that is an ancestor of (or is) the source window. + Otherwise, it is set to None. The state component gives the logical state of + the buttons on the core X pointer and modifier keys on the core X keyboard + just before the event. + The detail component type varies with the event type: + </para> + <informaltable pgwide='0' frame='all'> + <tgroup cols='2' align='center' colsep='1' rowsep='1'> + <colspec colname='c1' colwidth='2in'/> + <colspec colname='c2'/> + <tbody> + <row> + <entry align='left'>Event</entry> + <entry align='left'>Component</entry> + </row> + <row> + <entry align='left'>DeviceKeyPress</entry> + <entry align='left'>KEYCODE</entry> + </row> + <row> + <entry align='left'>DeviceKeyRelease</entry> + <entry align='left'>KEYCODE</entry> + </row> + <row> + <entry align='left'>DeviceButtonPress</entry> + <entry align='left'>BUTTON</entry> + </row> + <row> + <entry align='left'>DeviceButtonRelease</entry> + <entry align='left'>BUTTON</entry> + </row> + <row> + <entry align='left'>DeviceMotionNotify</entry> + <entry align='left'>{ Normal , Hint }</entry> + </row> + </tbody> + </tgroup> + </informaltable> + <para>The granularity of motion events is not guaranteed, but a client selecting + for motion events is guaranteed to get at least one event when a valuator + changes. If <emphasis>DeviceMotionHint</emphasis> is selected, the server is free to send + only one <emphasis>DeviceMotionNotify</emphasis> event (with detail <emphasis>Hint</emphasis>) to the + client for the event window, until either a key or button changes state, + the pointer leaves the event window, or the client issues a + <emphasis>QueryDeviceState</emphasis> or <emphasis>GetDeviceMotionEvents</emphasis> request.</para> + </sect2> + <sect2 id='devicevaluator_event'><title>DeviceValuator Event</title> + <para> + <literallayout> + DeviceValuator + device: CARD8 + device_state: SETofKEYBUTMASK + num_valuators: CARD8 + first_valuator: CARD8 + valuators: LISTofINT32 + </literallayout> + </para> + <para>DeviceValuator events are generated to contain valuator information for which + there is insufficient space in DeviceKey, DeviceButton, DeviceMotion, and + Proximity wire events. For events of these types, a second event of type + DeviceValuator follows immediately. The library combines these events into + a single event that a client can receive via XNextEvent. DeviceValuator + events are not selected for by clients, they only exist to contain information + that will not fit into some event selected by clients.</para> + <para>The device_state component gives the state of the + buttons and modifiers on the device generating the event.</para> + <para>Extension motion devices may report motion data for a variable number of + axes. The valuators array contains the values of all axes reported by the + device. If more than 6 axes are reported, more than one DeviceValuator event + will be sent by the server, and more than one DeviceKey, DeviceButton, + DeviceMotion, or Proximity event will be reported by the library. + Clients should examine the corresponding fields of the event reported by + the library to determine the total number of axes reported, and the first axis + reported in the current event. Axes are numbered beginning with zero.</para> + <para>For Button, Key and Motion events on a device reporting absolute motion data + the current value of the device's valuators is reported. For devices that + report relative data, Button and Key events may be followed by a DeviceValuator + event that contains 0s in the num_valuators field. In this case, only the + device_state component will have meaning.</para> + </sect2> + <sect2 id='device_focus_events'><title>Device Focus Events</title> + <para> + <literallayout> + DeviceFocusIn + DeviceFocusOut + device: CARD8 + time: TIMESTAMP + event: WINDOW + mode: { Normal, WhileGrabbed, Grab, Ungrab} + detail: { Ancestor, Virtual, Inferior, Nonlinear, + NonlinearVirtual, Pointer, PointerRoot, None} + </literallayout> + </para> + <para>These events are generated when the input focus changes and are reported to + clients selecting <emphasis>DeviceFocusChange</emphasis> for the specified device and window. + Events generated by <emphasis>SetDeviceFocus</emphasis> when the device is not grabbed + have mode <emphasis>Normal</emphasis>. Events generated by <emphasis>SetDeviceFocus</emphasis> when the + device is grabbed have mode <emphasis>WhileGrabbed</emphasis>. Events generated when a + device grab actives have mode <emphasis>Grab</emphasis>, and events generated when a device + grab deactivates have mode <emphasis>Ungrab</emphasis>.</para> + <para>All <emphasis>DeviceFocusOut</emphasis> events caused by a window unmap are generated after + any <emphasis>UnmapNotify</emphasis> event, but the ordering of <emphasis>DeviceFocusOut</emphasis> with + respect to generated <emphasis>EnterNotify</emphasis>, <emphasis>LeaveNotify</emphasis>, + <emphasis>VisibilityNotify</emphasis> and <emphasis>Expose</emphasis> events is not constrained.</para> + <para><emphasis>DeviceFocusIn</emphasis> and <emphasis>DeviceFocusOut</emphasis> events are generated for + focus changes of extension devices in the same manner as focus events for + the core devices are generated.</para> + </sect2> + <sect2 id='device_state_notify_event'><title>Device State Notify Event</title> + <para> + <literallayout> + DeviceStateNotify + time: TIMESTAMP + device: CARD8 + num_keys: CARD8 + num_buttons: CARD8 + num_valuators: CARD8 + classes_reported: CARD8 {SetOfDeviceMode | SetOfInputClass} + SetOfDeviceMode: + #x80 ProximityState 0 = InProxmity, 1 = OutOfProximity + #x40 Device Mode (0 = Relative, 1 = Absolute) + SetOfInputClass: #x04 reporting valuators + #x02 reporting buttons + #x01 reporting keys + buttons: LISTofCARD8 + keys: LISTofCARD8 + valuators: LISTofCARD32 + </literallayout> + </para> + <para>This event reports the state of the device just as in the + <emphasis>QueryDeviceState</emphasis> request. This event is reported to clients selecting + <emphasis>DeviceStateNotify</emphasis> for the device and window and is generated immediately + after every <emphasis>EnterNotify</emphasis> and <emphasis>DeviceFocusIn</emphasis>. If the device has + no more than 32 buttons, no more than 32 keys, and no more than 3 valuators, + This event can report the state of the device. If the device has more + than 32 buttons, the event will be immediately followed by a + DeviceButtonStateNotify event. If the device has more than 32 keys, the + event will be followed by a DeviceKeyStateNotify event. If the device has more + than 3 valuators, the event will be followed by one or more DeviceValuator + events.</para> + </sect2> + <sect2 id='device_keystate_and_buttonstate_notify_e'><title>Device KeyState and ButtonState Notify Events</title> + <para> + <literallayout> + DeviceKeyStateNotify + device: CARD8 + keys: LISTofCARD8 + + DeviceButtonStateNotify + device: CARD8 + buttons: LISTofCARD8 + </literallayout> + </para> + <para>These events contain information about the state of keys and buttons on a + device that will not fit into the DeviceStateNotify wire event. These events + are not selected by clients, rather they may immediately follow a + DeviceStateNotify wire event and be combined with it into a single + DeviceStateNotify client event that a client may receive via XNextEvent.</para> + </sect2> + <sect2 id='devicemappingnotify_event'><title>DeviceMappingNotify Event</title> + <para> + <literallayout> + DeviceMappingNotify + time: TIMESTAMP + device: CARD8 + request: CARD8 + first_keycode: CARD8 + count: CARD8 + </literallayout> + </para> + <para>This event reports a change in the mapping of keys, modifiers, or buttons on + an extension device. This event is reported to clients selecting + <emphasis>DeviceMappingNotify</emphasis> for the device and window and is generated + after every client <emphasis>SetDeviceButtonMapping</emphasis>, <emphasis>ChangeDeviceKeyMapping</emphasis>, + or <emphasis>ChangeDeviceModifierMapping</emphasis> request.</para> + </sect2> + <sect2 id='changedevicenotify_event'><title>ChangeDeviceNotify Event</title> + <para> + <literallayout> + ChangeDeviceNotify + device: CARD8 + time: TIMESTAMP + request: CARD8 + </literallayout> + </para> + <para>This event reports a change in the physical device being used as the core + X keyboard or X pointer device. + <emphasis>ChangeDeviceNotify</emphasis> events are reported to clients selecting + <emphasis>ChangeDeviceNotify</emphasis> for the device and window and is generated + after every client <emphasis>ChangeKeyboardDevice</emphasis> + or <emphasis>ChangePointerDevice</emphasis> request.</para> + </sect2> + <sect2 id='proximity_events'><title>Proximity Events</title> + <para> + <literallayout> + ProximityIn + ProximityOut + device: CARD8 + root, event: WINDOW + child: Window or None + same-screen: BOOL + root-x, root-y, event-x, event-y: INT16 + state: SETofKEYBUTMASK + time: TIMESTAMP + device-state: SETofKEYBUTMASK + axis-count: CARD8 + first-axis: CARD8 + axis-data: LISTofINT32 + </literallayout> + </para> + <para>These events are generated by some devices (such as graphics tablets or + touchscreens) to indicate that a stylus has moved into or out of contact + with a positional sensing surface.</para> + <para>The “source” of the event is the window the pointer is in. + The window with respect to which the event is normally reported is found + by looking up the hierarchy (starting with the source window) + for the first window on which any client has selected interest in the event. + The actual window used for reporting can be modified by active grabs and + by the focus window.The window the event is reported with respect to is called + the “event” window.</para> + <para>The root is the root window of the “source” window, and root-x and root-y + are the pointer coordinates relative to root's origin at the time of the event. + Event is the “event” window. If the event window is on the same screen as + root, then event-x and event-y are the pointer coordinates relative to the + event window's origin. Otherwise, event-x and event-y are zero. If the + source window is an inferior of the event window, then child is set to + the child of the event window that is an ancestor of (or is) the source window. + Otherwise, it is set to None. The state component gives the logical state of + the buttons on the core X pointer and modifier keys on the core X keyboard + just before the event. The device-state component gives the state of the + buttons and modifiers on the device generating the event.</para> + </sect2> + </sect1> </article> |