diff options
| author | Matt Dew <matt@osource.org> | 2010-07-10 09:48:13 -0400 |
|---|---|---|
| committer | Gaetan Nadon <memsize@videotron.ca> | 2010-07-10 09:48:13 -0400 |
| commit | d364aaaa47a69789b7acfd54b625caa299780480 (patch) | |
| tree | 1c03fd12f5ca896a6887ff4d48fcd866e7a51a2f | |
| parent | 30b076ea0b761c4a94c275be273accf311dc81c2 (diff) | |
specs: convert input .ms specs from xorg-docs module to DocBook XML
Signed-off-by: Gaetan Nadon <memsize@videotron.ca>
| -rw-r--r-- | Makefile.am | 2 | ||||
| -rw-r--r-- | configure.ac | 15 | ||||
| -rw-r--r-- | doc/.gitignore | 6 | ||||
| -rw-r--r-- | doc/Makefile.am | 66 | ||||
| -rw-r--r-- | doc/porting.xml | 1209 | ||||
| -rw-r--r-- | specs/.gitignore | 6 | ||||
| -rw-r--r-- | specs/Makefile.am | 68 | ||||
| -rw-r--r-- | specs/encoding.xml | 2312 | ||||
| -rw-r--r-- | specs/inputlib.xml | 70 | ||||
| -rw-r--r-- | specs/library.xml | 8559 |
10 files changed, 12307 insertions, 6 deletions
diff --git a/Makefile.am b/Makefile.am index e1118c4..14bfb26 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,4 +1,4 @@ -SUBDIRS = src man +SUBDIRS = src man doc specs pkgconfigdir = $(libdir)/pkgconfig pkgconfig_DATA = xi.pc diff --git a/configure.ac b/configure.ac index 16aab35..2f773f9 100644 --- a/configure.ac +++ b/configure.ac @@ -6,12 +6,15 @@ AC_INIT(libXi, 1.3, [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg], l AM_INIT_AUTOMAKE([foreign dist-bzip2]) AM_MAINTAINER_MODE -# Require xorg-macros: XORG_DEFAULT_OPTIONS +# Require xorg-macros minimum of 1.10 for DocBook XML documentation m4_ifndef([XORG_MACROS_VERSION], - [m4_fatal([must install xorg-macros 1.6 or later before running autoconf/autogen])]) -XORG_MACROS_VERSION(1.6) + [m4_fatal([must install xorg-macros 1.10 or later before running autoconf/autogen])]) +XORG_MACROS_VERSION(1.10) XORG_DEFAULT_OPTIONS +XORG_ENABLE_SPECS XORG_WITH_XMLTO(0.0.20) +XORG_WITH_FOP +XORG_CHECK_SGML_DOCTOOLS(1.5) XORG_WITH_ASCIIDOC(8.4.5) AM_CONFIG_HEADER(src/config.h) @@ -44,7 +47,9 @@ AM_CONDITIONAL([INSTALL_MANPAGES], XORG_CHECK_MALLOC_ZERO AC_OUTPUT([Makefile - src/Makefile - man/Makefile + src/Makefile + man/Makefile + doc/Makefile + specs/Makefile xi.pc]) diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 0000000..13312fe --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1,6 @@ +# Add & Override for this directory and it's subdirectories +*.html +*.ps +*.pdf +*.txt +*.css diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..651b114 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,66 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# 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: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# 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 AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS + +specdir = $(docdir)/$(subdir) +doc_sources = porting.xml +dist_spec_DATA = $(doc_sources) + +if HAVE_XMLTO +spec_DATA = $(doc_sources:.xml=.html) + +if HAVE_FOP +spec_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) +endif + +if HAVE_XMLTO_TEXT +spec_DATA += $(doc_sources:.xml=.txt) +endif + +if HAVE_STYLESHEETS +XMLTO_FLAGS = -m $(XSL_STYLESHEET) + +spec_DATA += xorg.css +xorg.css: $(STYLESHEET_SRCDIR)/xorg.css + $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@ +endif + +CLEANFILES = $(spec_DATA) + +SUFFIXES = .xml .ps .pdf .txt .html + +%.txt: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< + +%.html: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< + +%.pdf: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< + +%.ps: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< + +endif HAVE_XMLTO +endif ENABLE_SPECS diff --git a/doc/porting.xml b/doc/porting.xml new file mode 100644 index 0000000..1b2f1d7 --- /dev/null +++ b/doc/porting.xml @@ -0,0 +1,1209 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book 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+XMan by doclifter --> +<book id="porting"> + +<bookinfo> + <title>X11 Input Extension Porting Document</title> + <releaseinfo>X Version 11, Release 6.7</releaseinfo> + <authorgroup> + <author> + <firstname>George</firstname><surname>Sachs</surname> + <affiliation><orgname>Hewlett-Packard</orgname></affiliation> + </author> + </authorgroup> + <corpname>X Consortium Standard</corpname> + <copyright><year>1989</year><holder>Hewlett-Packard Company</holder></copyright> + <copyright><year>1990</year><holder>Hewlett-Packard Company</holder></copyright> + <copyright><year>1991</year><holder>Hewlett-Packard Company</holder></copyright> + + <copyright><year>1989</year><holder>X Consortium</holder></copyright> + <copyright><year>1990</year><holder>X Consortium</holder></copyright> + <copyright><year>1991</year><holder>X Consortium</holder></copyright> + <affiliation><orgname>X Consortium</orgname></affiliation> + <productnumber>X Version 11, Release 6.7</productnumber> + +<legalnotice> + + +<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. +Hewlett-Packard makes no representations about the suitability for any purpose of the information in this +document. It is provided "as is" without express or implied warranty. This document is only a draft stan- +dard of the X Consortium and is therefore subject to change. +</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>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.</para> + +<para>X Window System is a trademark of The Open Group.</para> +</legalnotice> + +</bookinfo> + +<chapter id="x11_input_extension_porting_document"> +<title>X11 Input Extension Porting Document</title> + +<para> +This document is intended to aid the process of integrating the +X11 Input Extension into an X server. +</para> +<para> +<!-- .LP --> +Most of the functionality provided by the input extension is +device- and implementation-independent, and should require no changes. +The functionality is implemented by +routines that typically reside in the server source tree directory +extensions/server/xinput. +This extension includes functions to enable and disable input extension devices, +select input, grab and focus those device, query and change key +and button mappings, and others. The only input extension requirements +for the device-dependent part of X are that the input devices be +correctly initialized and input events from those devices be correctly +generated. Device-dependent X is responsible for reading input data from +the input device hardware and if necessary, reformatting it into X events. +</para> +<para> +<!-- .LP --> +The process of initializing input extension devices is similar to that used +for the core devices, and is described in the following sections. When +multiple input devices are attached to X server, the choice of which devices +to initially use as the core X pointer and keyboard is left +implementation-dependent. It is also up to each implementation to decide +whether all input devices will be opened by the server during its +initialization and kept open for the life of the server. The alternative is +to open only the X keyboard and X pointer during server initialization, and +open other input devices only when requested by a client to do so. Either +type of implementation is supported by the input extension. +</para> +<para> +<!-- .LP --> +Input extension events generated by the X server use the same 32-byte xEvent +wire event as do core input events. However, additional information must be +sent for input extension devices, requiring that multiple xEvents be generated +each time data is received from an input extension device. These xEvents are +combined into a single client XEvent by the input extension library. A later +section of this document describes the format and generation of input extension +events. +</para> +<sect1 id="Initializing_Extension_Devices"> +<title>Initializing Extension Devices</title> +<para> +<!-- .LP --> +Extension input devices are initialized in the same manner as the core +X input devices. Device-Independent X provides functions that can be +called from DDX to initialize these devices. Which functions are called +and when will vary by implementation, and will depend on whether the +implementation opens all the input devices available to X when X is initialized, +or waits until a client requests that a device be opened. +In the simplest case, DDX will open all input devices as part of its +initialization, when the InitInput routine is called. +</para> +<sect2 id="Summary_of_Calling_Sequence"> +<title>Summary of Calling Sequence</title> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +Device-Independent X | Device-Dependent X +-------------------- | ------------------- + | +InitInput --------------> | - do device-specific initialization + | + | - call AddInputDevice (deviceProc,AutoStart) +AddInputDevice | + - creates DeviceIntRec | + - records deviceProc | + - adds new device to | + list of off_devices. | +sets dev->startup=AutoStart| + | - call one of: + | - RegisterPointerDevice (X pointer) + | - processInputProc = ProcessPointerEvents + | - RegisterKeyboardDevice (X keyboard) + | - processInputProc = ProcessKeyboardEvents + | - RegisterOtherDevice (extension device) + | - processInputProc = ProcessOtherEvents + | + | +InitAndStartDevices -----> | - calls deviceProc with parameters + | (DEVICE_INIT, AutoStart) +sets dev->inited = return | + value from deviceProc | + | + | - in deviceProc, do one of: + | - call InitPointerDeviceStruct (X pointer) + | - call InitKeyboardDeviceStruct (X keybd) + | - init extension device by calling some of: + | - InitKeyClassDeviceStruct + | - InitButtonClassDeviceStruct + | - InitValuatorClassDeviceStruct + | - InitValuatorAxisStruct + | - InitFocusClassDeviceStruct + | - InitProximityClassDeviceStruct + | - InitKbdFeedbackClassDeviceStruct + | - InitPtrFeedbackClassDeviceStruct + | - InitLedFeedbackClassDeviceStruct + | - InitStringFeedbackClassDeviceStruct + | - InitIntegerFeedbackClassDeviceStruct + | - InitBellFeedbackClassDeviceStruct + | - init device name and type by: + | - calling MakeAtom with one of the + | predefined names + | - calling AssignTypeAndName + | + | +for each device added | + by AddInputDevice, | + InitAndStartDevices | + calls EnableDevice if | - EnableDevice calls deviceProc with + dev->startup & | (DEVICE_ON, AutoStart) + dev->inited | + | +If deviceProc returns | - core devices are now enabled, extension + Success, EnableDevice | devices are now available to be accessed + move the device from | through the input extension protocol + inputInfo.off_devices | requests. + to inputInfo.devices | +</literallayout> +</para> +</sect2> +<sect2 id="Initialization_Called_From_InitInput"> +<title>Initialization Called From InitInput</title> +<para> +<!-- .LP --> +InitInput is the first DDX input entry point called during X server startup. +This routine is responsible for +device- and implementation- specific initialization, and for calling +AddInputDevice to create and initialize the DeviceIntRec structure for each +input device. AddInputDevice is passed the address of a procedure to be called +by the DIX routine InitAndStartDevices when input devices are enabled. +This procedure is expected to perform X initialization for the input device. +</para> +<para> +<!-- .LP --> +If the device is to be used as the X pointer, DDX should then call +RegisterPointerDevice, passing the DeviceIntRec pointer, +to initialize the device as the X pointer. +</para> +<para> +<!-- .LP --> +If the device is to be used as the X keyboard, DDX should instead call +RegisterKeyboardDevice to initialize the device as the X keyboard. +</para> +<para> +<!-- .LP --> +If the device is to be used as an extension device, DDX should instead +call RegisterOtherDevice, passing the DeviceIntPtr returned by +AddInputDevice. +</para> +<para> +<!-- .LP --> +A sample InitInput implementation is shown below. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +InitInput(argc,argv) + { + int i, numdevs, ReadInput(); + DeviceIntPtr dev; + LocalDevice localdevs[LOCAL_MAX_DEVS]; + DeviceProc kbdproc, ptrproc, extproc; + + /************************************************************** + * Open the appropriate input devices, determine which are + * available, and choose an X pointer and X keyboard device + * in some implementation-dependent manner. + ***************************************************************/ + + open_input_devices (&numdevs, localdevs); + + /************************************************************** + * Register a WakeupHandler to handle input when it is generated. + ***************************************************************/ + + RegisterBlockAndWakeupHandlers (NoopDDA, ReadInput, NULL); + + /************************************************************** + * Register the input devices with DIX. + ***************************************************************/ + + for (i=0; i<numdevs; i++) + { + if (localdevs[i].use == IsXKeyboard) + { + dev = AddInputDevice (kbdproc, TRUE); + RegisterKeyboardDevice (dev); + } + else if (localdevs[i].use == IsXPointer) + { + dev = AddInputDevice (ptrproc, TRUE); + RegisterPointerDevice (dev); + } + else + { + dev = AddInputDevice (extproc, FALSE); + RegisterOtherDevice (dev); + } + if (dev == NULL) + FatalError ("Too many input devices."); + dev->devicePrivate = (pointer) &localdevs[i]; + } +</literallayout> +</para> +</sect2> +<sect2 id="Initialization_Called_From_InitAndStartDevices"> +<title>Initialization Called From InitAndStartDevices</title> +<para> +<!-- .LP --> +After InitInput has returned, +InitAndStartDevices is the DIX routine that is called to enable input devices. +It calls the device control routine that was passed to AddInputDevice, +with a mode value of DEVICE_INIT. The action taken by the device control +routine depends on how the device is to be used. If the device is to be +the X pointer, the device control routine should call +InitPointerDeviceStruct to initialize it. If the device is to be the +X keyboard, the device control routine should call +InitKeyboardDeviceStruct. Since input extension devices may support various +combinations of keys, buttons, valuators, and feedbacks, +each class of input that it supports must be initialized. +Entry points are defined by DIX to initialize each of the supported classes of +input, and are described in the following sections. +</para> +<para> +<!-- .LP --> +A sample device control routine called from InitAndStartDevices is +shown below. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +Bool extproc (dev, mode) + DeviceIntPtr dev; + int mode; + { + LocalDevice *localdev = (LocalDevice *) dev->devicePrivate; + + switch (mode) + { + case DEVICE_INIT: + if (strcmp(localdev->name, XI_TABLET) == 0) + { + /**************************************************** + * This device reports proximity, has buttons, + * reports two axes of motion, and can be focused. + * It also supports the same feedbacks as the X pointer + * (acceleration and threshold can be set). + ****************************************************/ + + InitButtonClassDeviceStruct (dev, button_count, button_map); + InitValuatorClassDeviceStruct (dev, localdev->n_axes,); + motionproc, MOTION_BUF_SIZE, Absolute); + for (i=0; i<localdev->n_axes; i++) + InitValuatorAxisStruct (dev, i, min_val, max_val, + resolution); + InitFocusClassDeviceStruct (dev); + InitProximityClassDeviceStruct (dev); + InitPtrFeedbackClassDeviceStruct (dev, p_controlproc); + } + else if (strcmp(localdev->name, XI_BUTTONBOX) == 0) + { + /**************************************************** + * This device has keys and LEDs, and can be focused. + ****************************************************/ + + InitKeyClassDeviceStruct (dev, syms, modmap); + InitFocusClassDeviceStruct (dev); + InitLedFeedbackClassDeviceStruct (dev, ledcontrol); + } + else if (strcmp(localdev->name, XI_KNOBBOX) == 0) + { + /**************************************************** + * This device reports motion. + * It can be focused. + ****************************************************/ + + InitValuatorClassDeviceStruct (dev, localdev->n_axes,); + motionproc, MOTION_BUF_SIZE, Absolute); + for (i=0; i<localdev->n_axes; i++) + InitValuatorAxisStruct (dev, i, min_val, max_val, + resolution); + InitFocusClassDeviceStruct (dev); + } + localdev->atom = + MakeAtom(localdev->name, strlen(localdev->name), FALSE); + AssignTypeAndName (dev, localdev->atom, localdev->name); + break; + case DEVICE_ON: + AddEnabledDevice (localdev->file_ds); + dev->on = TRUE; + break; + case DEVICE_OFF: + dev->on = FALSE; + RemoveEnabledDevice (localdev->file_ds); + break; + case DEVICE_CLOSE: + break; + } + } +</literallayout> +</para> +<para> +<!-- .LP --> +The device control routine is called with a mode value of DEVICE_ON +by the DIX routine EnableDevice, which is called from InitAndStartDevices. +When called with this mode, it should call AddEnabledDevice to cause the +server to begin checking for available input from this device. +</para> +<para> +<!-- .LP --> +>From InitAndStartDevices, EnableDevice is called for all devices that have +the "inited" and "startup" fields in the DeviceIntRec set to TRUE. The +"inited" field is set by InitAndStartDevices to the value returned by +the deviceproc when called with a mode value of DEVICE_INIT. The "startup" +field is set by AddInputDevice to value of the second parameter (autoStart). +</para> +<para> +<!-- .LP --> +When the server is first initialized, it should only be checking for input +from the core X keyboard and pointer. One way to accomplish this is to +call AddInputDevice for the core X keyboard and pointer with an +autoStart value equal to TRUE, while calling AddInputDevice for +input extension devices with an autoStart value equal to FALSE. If this is +done, EnableDevice will skip all input extension devices during server +initialization. In this case, +the OpenInputDevice routine should set the "startup" field to TRUE +when called for input extension devices. This will cause ProcXOpenInputDevice +to call EnableDevice for those devices when a client first does an +XOpenDevice request. +</para> +</sect2> +<sect2 id="DIX_Input_Class_Initialization_Routines"> +<title>DIX Input Class Initialization Routines</title> +<para> +<!-- .LP --> +DIX routines are defined to initialize each of the defined input classes. +The defined classes are: +<!-- .RS --> +<!-- .in +5n --> +</para> +<itemizedlist> + <listitem> + <para> +KeyClass - the device has keys. + </para> + </listitem> + <listitem> + <para> +ButtonClass - the device has buttons. + </para> + </listitem> + <listitem> + <para> +ValuatorClass - the device reports motion data or positional data. + </para> + </listitem> + <listitem> + <para> +Proximitylass - the device reports proximity information. + </para> + </listitem> + <listitem> + <para> +FocusClass - the device can be focused. + </para> + </listitem> + <listitem> + <para> +FeedbackClass - the device supports some kind of feedback +<!-- .in -5n --> +<!-- .RE --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +DIX routines are provided to initialize the X pointer and keyboard, as in +previous releases of X. During X initialization, InitPointerDeviceStruct +is called to initialize the X pointer, and InitKeyboardDeviceStruct is +called to initialize the X keyboard. There is no +corresponding routine for extension input devices, since they do not all +support the same classes of input. Instead, DDX is responsible for the +initialization of the input classes supported by extension devices. +A description of the routines provided by DIX to perform that initialization +follows. +</para> +<sect3 id="InitKeyClassDeviceStruct"> +<title>InitKeyClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a KeyClassRec, and +should be called for extension devices that have keys. It is passed a pointer +to the device, and pointers to arrays of keysyms and modifiers reported by +the device. It returns FALSE if the KeyClassRec could not be allocated, +or if the maps for the keysyms and and modifiers could not be allocated. +Its parameters are: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +Bool +InitKeyClassDeviceStruct(dev, pKeySyms, pModifiers) + DeviceIntPtr dev; + KeySymsPtr pKeySyms; + CARD8 pModifiers[]; +</literallayout> +</para> +<para> +<!-- .LP --> +The DIX entry point InitKeyboardDeviceStruct calls this routine for the +core X keyboard. It must be called explicitly for extension devices +that have keys. +</para> +</sect3> +<sect3 id="InitButtonClassDeviceStruct"> +<title>InitButtonClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a ButtonClassRec, and +should be called for extension devices that have buttons. It is passed a +pointer to the device, the number of buttons supported, and a map of the +reported button codes. It returns FALSE if the ButtonClassRec could not be +allocated. Its parameters are: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +Bool +InitButtonClassDeviceStruct(dev, numButtons, map) + register DeviceIntPtr dev; + int numButtons; + CARD8 *map; +</literallayout> +</para> +<para> +<!-- .LP --> +The DIX entry point InitPointerDeviceStruct calls this routine for the +core X pointer. It must be called explicitly for extension devices that +have buttons. +</para> +</sect3> +<sect3 id="InitValuatorClassDeviceStruct"> +<title>InitValuatorClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a ValuatorClassRec, and +should be called for extension devices that have valuators. It is passed the +number of axes of motion reported by the device, the address of the motion +history procedure for the device, the size of the motion history buffer, +and the mode (Absolute or Relative) of the device. It returns FALSE if +the ValuatorClassRec could not be allocated. Its parameters are: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +Bool +InitValuatorClassDeviceStruct(dev, numAxes, motionProc, numMotionEvents, mode) + DeviceIntPtr dev; + int (*motionProc)(); + int numAxes; + int numMotionEvents; + int mode; +</literallayout> +</para> +<para> +<!-- .LP --> +The DIX entry point InitPointerDeviceStruct calls this routine for the +core X pointer. It must be called explicitly for extension devices that +report motion. +</para> +</sect3> +<sect3 id="InitValuatorAxisStruct"> +<title>InitValuatorAxisStruct</title> +<para> +<!-- .LP --> +This function is provided to initialize an XAxisInfoRec, and +should be called for core and extension devices that have valuators. +The space for the XAxisInfoRec is allocated by +the InitValuatorClassDeviceStruct function, but is not initialized. +</para> +<para> +<!-- .LP --> +InitValuatorAxisStruct should be called once for each axis of motion +reported by the device. Each +invocation should be passed the axis number (starting with 0), the +minimum value for that axis, the maximum value for that axis, and the +resolution of the device in counts per meter. If the device reports +relative motion, 0 should be reported as the minimum and maximum values. +InitValuatorAxisStruct has the following parameters: +<literallayout class="monospaced"> +InitValuatorAxisStruct(dev, axnum, minval, maxval, resolution) + DeviceIntPtr dev; + int axnum; + int minval; + int maxval; + int resolution; +</literallayout> +</para> +<para> +<!-- .LP --> +This routine is not called by InitPointerDeviceStruct for the +core X pointer. It must be called explicitly for core and extension devices +that report motion. +</para> +</sect3> +<sect3 id="InitFocusClassDeviceStruct"> +<title>InitFocusClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a FocusClassRec, and +should be called for extension devices that can be focused. It is passed a +pointer to the device, and returns FALSE if the allocation fails. +It has the following parameter: +<literallayout class="monospaced"> +Bool +InitFocusClassDeviceStruct(dev) + DeviceIntPtr dev; +</literallayout> +</para> +<para> +<!-- .LP --> +The DIX entry point InitKeyboardDeviceStruct calls this routine for the +core X keyboard. It must be called explicitly for extension devices +that can be focused. Whether or not a particular device can be focused +is left implementation-dependent. +</para> +</sect3> +<sect3 id="InitProximityClassDeviceStruct"> +<title>InitProximityClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a ProximityClassRec, and +should be called for extension absolute pointing devices that report proximity. +It is passed a pointer to the device, and returns FALSE if the allocation fails. +It has the following parameter: +<literallayout class="monospaced"> +Bool +InitProximityClassDeviceStruct(dev) + DeviceIntPtr dev; +</literallayout> +</para> +</sect3> +<sect3 id="Initializing_Feedbacks"> +<title>Initializing Feedbacks</title> +<para> +<!-- .LP --> +</para> +<sect4 id="InitKbdFeedbackClassDeviceStruct"> +<title>InitKbdFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a KbdFeedbackClassRec, and +may be called for extension devices that support some or all of the +feedbacks that the core keyboard supports. It is passed a +pointer to the device, a pointer to the procedure that sounds the bell, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitKbdFeedbackClassDeviceStruct(dev, bellProc, controlProc) + DeviceIntPtr dev; + void (*bellProc)(); + void (*controlProc)(); +</literallayout> +The DIX entry point InitKeyboardDeviceStruct calls this routine for the +core X keyboard. It must be called explicitly for extension devices +that have the same feedbacks as a keyboard. Some feedbacks, such as LEDs and +bell, can be supported either with a KbdFeedbackClass or with BellFeedbackClass +and LedFeedbackClass feedbacks. +</para> +</sect4> +<sect4 id="InitPtrFeedbackClassDeviceStruct"> +<title>InitPtrFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a PtrFeedbackClassRec, and +should be called for extension devices that allow the setting of acceleration +and threshold. It is passed a pointer to the device, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitPtrFeedbackClassDeviceStruct(dev, controlProc) + DeviceIntPtr dev; + void (*controlProc)(); +</literallayout> +</para> +<para> +<!-- .LP --> +The DIX entry point InitPointerDeviceStruct calls this routine for the +core X pointer. It must be called explicitly for extension devices +that support the setting of acceleration and threshold. +</para> +</sect4> +<sect4 id="InitLedFeedbackClassDeviceStruct"> +<title>InitLedFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a LedFeedbackClassRec, and +should be called for extension devices that have LEDs. +It is passed a pointer to the device, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitLedFeedbackClassDeviceStruct(dev, controlProc) + DeviceIntPtr dev; + void (*controlProc)(); +</literallayout> +</para> +<para> +<!-- .LP --> +Up to 32 LEDs per feedback can be supported, and a device may have +multiple feedbacks of the same type. +</para> +</sect4> +<sect4 id="InitBellFeedbackClassDeviceStruct"> +<title>InitBellFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a BellFeedbackClassRec, +and should be called for extension devices that have a bell. +It is passed a pointer to the device, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitBellFeedbackClassDeviceStruct(dev, bellProc, controlProc) + DeviceIntPtr dev; + void (*bellProc)(); + void (*controlProc)(); +</literallayout> +</para> +</sect4> +<sect4 id="InitStringFeedbackClassDeviceStruct"> +<title>InitStringFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize a StringFeedbackClassRec, +and should be called for extension devices that have a display upon which a +string can be displayed. +It is passed a pointer to the device, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitStringFeedbackClassDeviceStruct(dev, controlProc, max_symbols, + num_symbols_supported, symbols) + DeviceIntPtr dev; + void (*controlProc)(); + int max_symbols: + int num_symbols_supported; + KeySym *symbols; +</literallayout> +</para> +</sect4> +<sect4 id="InitIntegerFeedbackClassDeviceStruct"> +<title>InitIntegerFeedbackClassDeviceStruct</title> +<para> +<!-- .LP --> +This function is provided to allocate and initialize an +IntegerFeedbackClassRec, +and should be called for extension devices that have a display upon which an +integer can be displayed. +It is passed a pointer to the device, +and a pointer to the device control procedure. +It returns FALSE if the allocation fails, and has the following parameters: +<literallayout class="monospaced"> +Bool +InitIntegerFeedbackClassDeviceStruct(dev, controlProc) + DeviceIntPtr dev; + void (*controlProc)(); +</literallayout> +</para> +</sect4> +</sect3> +</sect2> +<sect2 id="Initializing_The_Device_Name_And_Type"> +<title>Initializing The Device Name And Type</title> +<para> +<!-- .LP --> +The device name and type can be initialized by calling AssignTypeAndName +with the following parameters: +<literallayout class="monospaced"> +void +AssignTypeAndName(dev, type, name) + DeviceIntPtr dev; + Atom type; + char *name; +</literallayout> +</para> +<para> +<!-- .LP --> +This will allocate space for the device name and copy the name that was passed. +The device type can be obtained by calling MakeAtom with one of the names +defined for input devices. MakeAtom has the following parameters: +<literallayout class="monospaced"> +Atom +MakeAtom(name, len, makeit) + char *name; + int len; + Bool makeit; +</literallayout> +</para> +<para> +<!-- .LP --> +Since the atom was already made when the input extension was initialized, the +value of makeit should be FALSE; +</para> +</sect2> +</sect1> +<sect1 id="Closing_Extension_Devices"> +<title>Closing Extension Devices</title> +<para> +<!-- .LP --> +The DisableDevice entry point is provided by DIX to disable input devices. +It calls the device control routine for the specified +device with a mode value of DEVICE_OFF. The device control routine should +call RemoveEnabledDevice to stop the server from checking for input from +that device. +</para> +<para> +<!-- .LP --> +DisableDevice is not called by any input extension routines. It can be +called from the CloseInputDevice routine, which is called by +ProcXCloseDevice when a client makes an XCloseDevice request. If +DisableDevice is called, it should only be called when the last client +using the extension device has terminated or called XCloseDevice. +</para> +</sect1> +<sect1 id="Implementation_Dependent_Routines"> +<title>Implementation-Dependent Routines</title> +<para> +<!-- .LP --> +Several input extension protocol requests have +implementation-dependent entry points. Default routines +are defined for these entry points and contained in the source +file extensions/server/xinput/xstubs.c. Some implementations may +be able to use the default routines without change. +The following sections describe each of these routines. +</para> +<sect2 id="AddOtherInputDevices"> +<title>AddOtherInputDevices</title> +<para> +<!-- .LP --> +AddOtherInputDevice is called from ProcXListInputDevices as a result of +an XListInputDevices protocol request. It may be needed by +implementations that do not open extension input devices until requested +to do so by some client. These implementations may not initialize +all devices when the X server starts up, because some of those devices +may be in use. Since the XListInputDevices +function only lists those devices that have been initialized, +AddOtherInputDevices is called to give DDX a chance to +initialize any previously unavailable input devices. +</para> +<para> +<!-- .LP --> +A sample AddOtherInputDevices routine might look like the following: +<literallayout class="monospaced"> +void +AddOtherInputDevices () + { + DeviceIntPtr dev; + int i; + + for (i=0; i<MAX_DEVICES; i++) + { + if (!local_dev[i].initialized && available(local_dev[i])) + { + dev = (DeviceIntPtr) AddInputDevice (local_dev[i].deviceProc, TRUE); + dev->public.devicePrivate = local_dev[i]; + RegisterOtherDevice (dev); + dev->inited = ((*dev->deviceProc)(dev, DEVICE_INIT) == Success); + } + } + } +</literallayout> +</para> +<para> +<!-- .LP --> +The default AddOtherInputDevices routine in xstubs.c does nothing. +If all input extension devices are initialized when the server +starts up, it can be left as a null routine. +</para> +</sect2> +<sect2 id="OpenInputDevice"> +<title>OpenInputDevice</title> +<para> +<!-- .LP --> +Some X server implementations open all input devices when the server +is initialized and never close them. Other implementations may open only +the X pointer and keyboard devices during server initialization, +and open other input devices only when some client makes an +XOpenDevice request. This entry point is for the latter type of +implementation. +</para> +<para> +<!-- .LP --> +If the physical device is not already open, it can be done in this routine. +In this case, the server must keep track of the fact that one or more clients +have the device open, and physically close it when the last client that has +it open makes an XCloseDevice request. +</para> +<para> +<!-- .LP --> +The default implementation is to do nothing (assume all input devices +are opened during X server initialization and kept open). +</para> +</sect2> +<sect2 id="CloseInputDevice"> +<title>CloseInputDevice</title> +<para> +<!-- .LP --> +Some implementations may close an input device when the last client +using that device requests that it be closed, or terminates. +CloseInputDevice is called from ProcXCloseDevice when a client +makes an XCloseDevice protocol request. +</para> +<para> +<!-- .LP --> +The default implementation is to do nothing (assume all input devices +are opened during X server initialization and kept open). +</para> +</sect2> +<sect2 id="SetDeviceMode"> +<title>SetDeviceMode</title> +<para> +<!-- .LP --> +Some implementations support input devices that can report +either absolute positional data or relative motion. The XSetDeviceMode +protocol request is provided to allow DDX to change the current mode of +such a device. +</para> +<para> +<!-- .LP --> +The default implementation is to always return a BadMatch error. If the +implementation does not support any input devices that are capable of +reporting both relative motion and absolute position information, the +default implementation may be left unchanged. +</para> +</sect2> +<sect2 id="SetDeviceValuators"> +<title>SetDeviceValuators</title> +<para> +<!-- .LP --> +Some implementations support input devices that allow their valuators to be +set to an initial value. The XSetDeviceValuators +protocol request is provided to allow DDX to set the valuators of +such a device. +</para> +<para> +<!-- .LP --> +The default implementation is to always return a BadMatch error. If the +implementation does not support any input devices that are allow their +valuators to be set, the default implementation may be left unchanged. +</para> +</sect2> +<sect2 id="ChangePointerDevice"> +<title>ChangePointerDevice</title> +<para> +<!-- .LP --> +The XChangePointerDevice protocol request is provided to change which device is +used as the X pointer. Some implementations may maintain information +specific to the X pointer in the private data structure pointed to by +the DeviceIntRec. ChangePointerDevice is called to allow such +implementations to move that information to the new pointer device. +The current location of the X cursor is an example of the type of +information that might be affected. +</para> +<para> +<!-- .LP --> +The DeviceIntRec structure that describes the X pointer device does not +contain a FocusRec. If the device that has been made into the new X pointer +was previously a device that could be focused, ProcXChangePointerDevice will +free the FocusRec associated with that device. +</para> +<para> +<!-- .LP --> +If the server implementation desires to allow clients to focus the old pointer +device (which is now accessible through the input extension), it should call +InitFocusClassDeviceStruct for the old pointer device. +</para> +<para> +<!-- .LP --> +The XChangePointerDevice protocol request also allows the client +to choose which axes of the new pointer device are used to move +the X cursor in the X- and Y- directions. If the axes are different +than the default ones, the server implementation should record that fact. +</para> +<para> +<!-- .LP --> +If the server implementation supports input devices with valuators that +are not allowed to be used as the X pointer, they should be screened out +by this routine and a BadDevice error returned. +</para> +<para> +<!-- .LP --> +The default implementation is to do nothing. +</para> +</sect2> +<sect2 id="ChangeKeyboardDevice"> +<title>ChangeKeyboardDevice</title> +<para> +<!-- .LP --> +The XChangeKeyboardDevice protocol request is provided to change which device is +used as the X keyboard. Some implementations may maintain information +specific to the X keyboard in the private data structure pointed to by +the DeviceIntRec. ChangeKeyboardDevice is called to allow such +implementations to move that information to the new keyboard device. +</para> +<para> +<!-- .LP --> +The X keyboard device can be focused, and the DeviceIntRec that describes +that device has a FocusRec. If the device that has been made into the new X +keyboard did not previously have a FocusRec, +ProcXChangeKeyboardDevice will allocate one for it. +</para> +<para> +<!-- .LP --> +If the implementation does not want clients to be able to focus the old X +keyboard (which has now become available as an input extension device) +it should call DeleteFocusClassDeviceStruct to free the FocusRec. +</para> +<para> +<!-- .LP --> +If the implementation supports input devices with keys that are not allowed +to be used as the X keyboard, they should be checked for here, and a +BadDevice error returned. +</para> +<para> +<!-- .LP --> +The default implementation is to do nothing. +</para> +</sect2> +</sect1> +<sect1 id="Input_Extension_Events"> +<title>Input Extension Events</title> +<para> +<!-- .LP --> +Events accessed through the input extension are analogous to the core input +events, but have different event types. They are of types +<function>DeviceKeyPress</function>, <function>DeviceKeyRelease</function>, <function>DeviceButtonPress</function>, +<function>DeviceButtonRelease</function>, <function>DeviceDeviceMotionNotify</function>, +<function>DeviceProximityIn</function>, <function>DeviceProximityOut</function>, and <function>DeviceValuator</function>. +These event types are not constants. Instead, they are external integers +defined by the input extension. Their actual values will depend on which +extensions are supported by a server, and the order in which they are +initialized. +</para> +<para> +<!-- .LP --> +The data structures that define these +events are defined in the file <function>extensions/include/XIproto.h</function>. Other +input extension constants needed by DDX are defined in the file +<function>extensions/include/XI.h</function>. +</para> +<para> +<!-- .LP --> +Some events defined by the input extension contain more information than can +be contained in the 32-byte xEvent data structure. To send this information +to clients, DDX must generate two or more 32-byte wire events. The following +sections describe the contents of these events. +</para> +<sect2 id="Device_Key_Events"> +<title>Device Key Events</title> +<para> +<!-- .LP --> +<function>DeviceKeyPresss</function> events contain all the information that is contained in +a core <function>KeyPress</function> event, and also the following additional information: +</para> +<para> +<!-- .LP --> +<!-- .RS --> +<!-- .in +5n --> +</para> +<itemizedlist> + <listitem> + <para> +deviceid - the identifier of the device that generated the event. + </para> + </listitem> + <listitem> + <para> +device_state - the state of any modifiers on the device that generated the event + </para> + </listitem> + <listitem> + <para> +num_valuators - the number of valuators reported in this event. + </para> + </listitem> + <listitem> + <para> +first_valuator - the first valuator reported in this event. + </para> + </listitem> + <listitem> + <para> +valuator0 through valuator5 - the values of the valuators. +<!-- .in -5n --> +<!-- .RE --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +In order to pass this information to the input extension library, two 32-byte +wire events must be generated by DDX. The first has an event type of +<function>DeviceKeyPress</function>, and the second has an event type of \fPDeviceValuator\fP. +</para> +<para> +<!-- .LP --> +The following code fragment shows how the two wire events could be initialized: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> + extern int DeviceKeyPress; + DeviceIntPtr dev; + xEvent xE[2]; + CARD8 id, num_valuators; + INT16 x, y, pointerx, pointery; + Time timestamp; + deviceKeyButtonPointer *xev = (deviceKeyButtonPointer *) xE; + deviceValuator *xv; + + xev->type = DeviceKeyPress; /* defined by input extension */ + xev->detail = keycode; /* key pressed on this device */ + xev->time = timestamp; /* same as for core events */ + xev->rootX = pointerx; /* x location of core pointer */ + xev->rootY = pointery; /* y location of core pointer */ + + /******************************************************************/ + /* */ + /* The following field does not exist for core input events. */ + /* It contains the device id for the device that generated the */ + /* event, and also indicates whether more than one 32-byte wire */ + /* event is being sent. */ + /* */ + /******************************************************************/ + + xev->deviceid = dev->id | MORE_EVENTS; /* sending more than 1*/ + + /******************************************************************/ + /* Fields in the second 32-byte wire event: */ + /******************************************************************/ + + xv = (deviceValuator *) ++xev; + xv->type = DeviceValuator; /* event type of second event */ + xv->deviceid = dev->id; /* id of this device */ + xv->num_valuators = 0; /* no valuators being sent */ + xv->device_state = 0; /* will be filled in by DIX */ +</literallayout> +</para> +</sect2> +<sect2 id="Device_Button_Events"> +<title>Device Button Events</title> +<para> +<!-- .LP --> +<function>DeviceButton</function> events contain all the information that is contained in +a core button event, and also the same additional information that a +<function>DeviceKey</function> event contains. +</para> +</sect2> +<sect2 id="Device_Motion_Events"> +<title>Device Motion Events</title> +<para> +<!-- .LP --> +<function>DeviceMotion</function> events contain all the information that is contained in +a core motion event, and also additional valuator information. At least +two wire events are required to contain this information. +The following code fragment shows how the two wire events could be initialized: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> + extern int DeviceMotionNotify; + DeviceIntPtr dev; + xEvent xE[2]; + CARD8 id, num_valuators; + INT16 x, y, pointerx, pointery; + Time timestamp; + deviceKeyButtonPointer *xev = (deviceKeyButtonPointer *) xE; + deviceValuator *xv; + + xev->type = DeviceMotionNotify; /* defined by input extension */ + xev->detail = keycode; /* key pressed on this device */ + xev->time = timestamp; /* same as for core events */ + xev->rootX = pointerx; /* x location of core pointer */ + xev->rootY = pointery; /* y location of core pointer */ + + /******************************************************************/ + /* */ + /* The following field does not exist for core input events. */ + /* It contains the device id for the device that generated the */ + /* event, and also indicates whether more than one 32-byte wire */ + /* event is being sent. */ + /* */ + /******************************************************************/ + + xev->deviceid = dev->id | MORE_EVENTS; /* sending more than 1*/ + + /******************************************************************/ + /* Fields in the second 32-byte wire event: */ + /******************************************************************/ + + xv = (deviceValuator *) ++xev; + xv->type = DeviceValuator; /* event type of second event */ + xv->deviceid = dev->id; /* id of this device */ + xv->num_valuators = 2; /* 2 valuators being sent */ + xv->first_valuator = 0; /* first valuator being sent */ + xv->device_state = 0; /* will be filled in by DIX */ + xv->valuator0 = x; /* first axis of this device */ + xv->valuator1 = y; /* second axis of this device */ +</literallayout> +</para> +<para> +<!-- .LP --> +Up to six axes can be reported in the deviceValuator event. If the device +is reporting more than 6 axes, additional pairs of DeviceMotionNotify and +DeviceValuator events should be sent, with the first_valuator field +set correctly. +</para> +</sect2> +<sect2 id="Device_Proximity_Events"> +<title>Device Proximity Events</title> +<para> +<!-- .LP --> +Some input devices that report absolute positional information, such as +graphics tablets and touchscreens, may report proximity events. +<function>ProximityIn</function> +events are generated when a pointing device like a stylus, or in the case +of a touchscreen, the user's finger, comes into close proximity with the +surface of the input device. <function>ProximityOut</function> events are generated when +the stylus or finger leaves the proximity of the input devices surface. +</para> +<para> +<!-- .LP --> +<function>Proximity</function> events contain almost the same information as button events. +The event type is <function>ProximityIn</function> or <function>ProximityOut</function>, and there is no +detail information. +<!-- .bp --> +<!-- .\" .TC --> + +</para> +</sect2> +</sect1> +</chapter> +</book> diff --git a/specs/.gitignore b/specs/.gitignore new file mode 100644 index 0000000..13312fe --- /dev/null +++ b/specs/.gitignore @@ -0,0 +1,6 @@ +# Add & Override for this directory and it's subdirectories +*.html +*.ps +*.pdf +*.txt +*.css diff --git a/specs/Makefile.am b/specs/Makefile.am new file mode 100644 index 0000000..93e8e85 --- /dev/null +++ b/specs/Makefile.am @@ -0,0 +1,68 @@ +# +# Copyright 2009 Sun Microsystems, Inc. All rights reserved. +# +# 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: +# +# The above copyright notice and this permission notice (including the next +# paragraph) shall be included in all copies or substantial portions of the +# Software. +# +# 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 AUTHORS OR COPYRIGHT HOLDERS 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. +# + +if ENABLE_SPECS + +specdir = $(docdir)/$(subdir) +doc_sources = inputlib.xml +dist_spec_DATA = $(doc_sources) \ + library.xml \ + encoding.xml + +if HAVE_XMLTO +spec_DATA = $(doc_sources:.xml=.html) + +if HAVE_FOP +spec_DATA += $(doc_sources:.xml=.ps) $(doc_sources:.xml=.pdf) +endif + +if HAVE_XMLTO_TEXT +spec_DATA += $(doc_sources:.xml=.txt) +endif + +if HAVE_STYLESHEETS +XMLTO_FLAGS = -m $(XSL_STYLESHEET) + +spec_DATA += xorg.css +xorg.css: $(STYLESHEET_SRCDIR)/xorg.css + $(AM_V_GEN)cp -pf $(STYLESHEET_SRCDIR)/xorg.css $@ +endif + +CLEANFILES = $(spec_DATA) + +SUFFIXES = .xml .ps .pdf .txt .html + +%.txt: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) txt $< + +%.html: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) xhtml-nochunks $< + +%.pdf: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop pdf $< + +%.ps: %.xml $(dist_spec_DATA) + $(AM_V_GEN)$(XMLTO) $(XMLTO_FLAGS) --with-fop ps $< + +endif HAVE_XMLTO +endif ENABLE_SPECS diff --git a/specs/encoding.xml b/specs/encoding.xml new file mode 100644 index 0000000..7b4bceb --- /dev/null +++ b/specs/encoding.xml @@ -0,0 +1,2312 @@ +<appendix id="input_extension_protocol_encoding"> +<title>Input Extension Protocol Encoding</title> +<para> +<function>Syntactic Conventions</function> +</para> +<para> +<!-- .LP --> +All numbers are in decimal, +unless prefixed with #x, in which case they are in hexadecimal (base 16). +</para> +<para> +<!-- .LP --> +The general syntax used to describe requests, replies, errors, events, and +compound types is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<function>NameofThing</function> + encode-form + ... + encode-form +</literallayout> +Each encode-form describes a single component. +</para> +<para> +<!-- .LP --> +For components described in the protocol as: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +name: TYPE +</literallayout> +the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +N TYPE name +</literallayout> +N is the number of bytes occupied in the data stream, +and TYPE is the interpretation of those bytes. +For example, +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i --> +<!-- .ta 1i 1.5i --> +depth: CARD8 +</literallayout> +becomes: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +1 CARD8 depth +</literallayout> +For components with a static numeric value the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +N value name +</literallayout> +The value is always interpreted as an N-byte unsigned integer. +For example, +the first two bytes of a Window error are always zero (indicating an +error in general) and three (indicating the Window error in particular): +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +1 0 Error +1 3 code +</literallayout> +For components described in the protocol as: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +name: <function>{Name1, ..., NameI}</function> +</literallayout> +</para> +<para> +<!-- .LP --> +the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +N name + value1 Name1 + ... + valueI NameI +</literallayout> +The value is always interpreted as an N-byte unsigned integer. +Note that the size of N is sometimes larger than that strictly required +to encode the values. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +class: <function>{InputOutput, InputOnly, CopyFromParent}</function> +</literallayout> +</para> +<para> +<!-- .LP --> +becomes: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i 3i --> +<!-- .ta 1i 1.5i 2.5i 3i --> +2 class + 0 CopyFromParent + 1 InputOutput + 2 InputOnly +</literallayout> +For components described in the protocol as: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +NAME: TYPE or <function>Alternative1 ... or AlternativeI</function> +</literallayout> +</para> +<para> +<!-- .LP --> +the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i 3i --> +<!-- .ta 1i 1.5i 2i 2.5i 3i --> +N TYPE NAME + value1 Alternative1 + ... + valueI AlternativeI +</literallayout> +The alternative values are guaranteed not to conflict with the encoding +of TYPE. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +destination: WINDOW or <function>PointerWindow</function> or <function>InputFocus</function> +</literallayout> +</para> +<para> +<!-- .LP --> +becomes: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2.5i --> +<!-- .ta 1i 1.5i 2.5i --> +4 WINDOW destination + 0 PointerWindow + 1 InputFocus +</literallayout> +For components described in the protocol as: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i --> +<!-- .ta 1i 1.5i --> +value-mask: BITMASK +</literallayout> +the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i --> +<!-- .ta 1i 1.5i 2i 2.5i --> +N BITMASK value-mask + mask1 mask-name1 + ... + maskI mask-nameI +</literallayout> +The individual bits in the mask are specified and named, +and N is 2 or 4. +The most-significant bit in a BITMASK is reserved for use in defining +chained (multiword) bitmasks, as extensions augment existing core requests. +The precise interpretation of this bit is not yet defined here, +although a probable mechanism is that a 1-bit indicates that another N bytes +of bitmask follows, with bits within the overall mask still interpreted +from least-significant to most-significant with an N-byte unit, with N-byte units +interpreted in stream order, and with the overall mask being byte-swapped +in individual N-byte units. +</para> +<para> +<!-- .LP --> +For LISTofVALUE encodings, the request is followed by a section of the form: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i --> +<!-- .ta 1i 1.5i --> +VALUEs + encode-form + ... + encode-form +</literallayout> +listing an encode-form for each VALUE. +The NAME in each encode-form keys to the corresponding BITMASK bit. +The encoding of a VALUE always occupies four bytes, +but the number of bytes specified in the encoding-form indicates how +many of the least-significant bytes are actually used; +the remaining bytes are unused and their values do not matter. +</para> +<para> +<!-- .LP --> +In various cases, the number of bytes occupied by a component will be specified +by a lowercase single-letter variable name instead of a specific numeric +value, and often some other component will have its value specified as a +simple numeric expression involving these variables. +Components specified with such expressions are always interpreted +as unsigned integers. +The scope of such variables is always just the enclosing request, reply, +error, event, or compound type structure. +For example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i --> +<!-- .ta 1i 1.5i 2i 2.5i --> +2 3+n request length +4n LISTofPOINT points +</literallayout> +For unused bytes (the values of the bytes are undefined and do not matter), +the encode-form is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i --> +<!-- .ta 1i 1.5i 2i 2.5i --> +N unused +</literallayout> +If the number of unused bytes is variable, the encode-form typically is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i --> +<!-- .ta 1i 1.5i 2i 2.5i --> +p unused, p=pad(E) +</literallayout> +where E is some expression, +and pad(E) is the number of bytes needed to round E up to a multiple of four. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA 1i 1.5i 2i 2.5i --> +<!-- .ta 1i 1.5i 2i 2.5i --> +pad(E) = (4 - (E mod 4)) mod 4 +</literallayout> +<!-- .ps +2 --> +<function>Common Types</function> +<!-- .ps --> +</para> +<para> +<!-- .LP --> +LISTofFOO +</para> +<itemizedlist> + <listitem> + <para> +In this document the LISTof notation strictly means some number of repetitions +of the FOO encoding; +the actual length of the list is encoded elsewhere. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +SETofFOO +</para> +<itemizedlist> + <listitem> + <para> +A set is always represented by a bitmask, with a 1-bit indicating presence in +the set. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +BITMASK: CARD32 +</para> +<para> +<!-- .LP --> +WINDOW: CARD32 +</para> +<para> +<!-- .LP --> +BYTE: 8-bit value +</para> +<para> +<!-- .LP --> +INT8: 8-bit signed integer +</para> +<para> +<!-- .LP --> +INT16: 16-bit signed integer +</para> +<para> +<!-- .LP --> +INT32: 32-bit signed integer +</para> +<para> +<!-- .LP --> +CARD8: 8-bit unsigned integer +</para> +<para> +<!-- .LP --> +CARD16: 16-bit unsigned integer +</para> +<para> +<!-- .LP --> +CARD32: 32-bit unsigned integer +</para> +<para> +<!-- .LP --> +TIMESTAMP: CARD32 +</para> +<para> +<!-- .LP --> +EVENTCLASS: CARD32 +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +INPUTCLASS + 0 KeyClass + 1 ButtonClass + 2 ValuatorClass + 3 FeedbackClass + 4 ProximityClass + 5 FocusClass + 6 OtherClass +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +INPUTCLASS + 0 KbdFeedbackClass + 1 PtrFeedbackClass + 2 StringFeedbackClass + 3 IntegerFeedbackClass + 4 LedFeedbackClass + 5 BellFeedbackClass +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +INPUTINFO + 0 KEYINFO + 1 BUTTONINFO + 2 VALUATORINFO +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +DEVICEMODE + 0 Relative + 1 Absolute +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +PROXIMITYSTATE + 0 InProximity + 1 OutOfProximity +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +BOOL + 0 False + 1 True +</literallayout> +</para> +<para> +<!-- .LP --> +KEYSYM: CARD32 +</para> +<para> +<!-- .LP --> +KEYCODE: CARD8 +</para> +<para> +<!-- .LP --> +BUTTON: CARD8 +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +SETofKEYBUTMASK + #x0001 Shift + #x0002 Lock + #x0004 Control + #x0008 Mod1 + #x0010 Mod2 + #x0020 Mod3 + #x0040 Mod4 + #x0080 Mod5 + #x0100 Button1 + #x0200 Button2 + #x0400 Button3 + #x0800 Button4 + #x1000 Button5 + #xe000 unused but must be zero +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .75i 1.75i --> +<!-- .ta .75i 1.75i --> +SETofKEYMASK + encodings are the same as for SETofKEYBUTMASK, except with + #xff00 unused but must be zero +</literallayout> +</para> +<para> +<!-- .LP --> +STRING8: LISTofCARD8 +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +STR + 1 n length of name in bytes + n STRING8 name +</literallayout> +<!-- .ps +2 --> +<function>Errors</function> +<!-- .ps --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Request + 1 0 Error + 1 1 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Value + 1 0 Error + 1 2 code + 2 CARD16 sequence number + 4 <32-bits> bad value + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Window + 1 0 Error + 1 3 code + 2 CARD16 sequence number + 4 CARD32 bad resource id + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Match + 1 0 Error + 1 8 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Access + 1 0 Error + 1 10 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Alloc + 1 0 Error + 1 11 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Name + 1 0 Error + 1 15 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Device + 1 0 Error + 1 CARD8 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Event + 1 0 Error + 1 CARD8 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Mode + 1 0 Error + 1 CARD8 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +Class + 1 0 Error + 1 CARD8 code + 2 CARD16 sequence number + 4 unused + 2 CARD16 minor opcode + 1 CARD8 major opcode + 21 unused +</literallayout> +<!-- .ps +2 --> +Keyboards +<!-- .ps --> +</para> +<para> +<!-- .LP --> +KEYCODE values are always greater than 7 (and less than 256). +</para> +<para> +<!-- .LP --> +KEYSYM values with the bit #x10000000 set are reserved as vendor-specific. +</para> +<para> +<!-- .LP --> +The names and encodings of the standard KEYSYM values are contained in +<!-- .\"Appendix B, Keysym Encoding. --> +appendix F. +</para> +<para> +<!-- .LP --> +<!-- .ps +2 --> +Pointers +<!-- .ps --> +</para> +<para> +<!-- .LP --> +BUTTON values are numbered starting with one. +</para> +<para> +<!-- .LP --> +<!-- .ps +2 --> +Requests +<!-- .ps --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetExtensionVersion + 1 CARD8 input extension opcode + 1 1 GetExtensionVersion opcode + 2 2+(n+p)/4 request length + 2 n length of name + 2 unused + n STRING8 name + p unused, p=pad(n) +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 1 GetExtensionVersion opcode + 2 CARD16 sequence number + 4 0 reply length + 2 CARD16 major version + 2 CARD16 minor version + 1 BOOL present + 19 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ListInputDevices + 1 CARD8 input extension opcode + 1 2 ListInputDevices opcode + 2 1 request length +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 2 ListInputDevices opcode + 2 CARD16 sequence number + 4 (n+p)/4 reply length + 1 CARD8 number of input devices + 23 unused + n LISTofDEVICEINFO info for each input device + p unused, p=pad(n) +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + DEVICEINFO + 4 CARD32 device type + 1 CARD8 device id + 1 CARD8 number of input classes this device reports + 1 CARD8 device use + 0 IsXPointer + 1 IsXKeyboard + 2 IsXExtensionDevice + 1 unused + n LISTofINPUTINFO input info for each input class + m STR name + p unused, p=pad(m) +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + INPUTINFO KEYINFO or BUTTONINFO or VALUATORINFO +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + KEYINFO + 1 0 class id + 1 8 length + 1 KEYCODE minimum keycode + 1 KEYCODE maximum keycode + 2 CARD16 number of keys + 2 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +BUTTONINFO + 1 1 class id + 1 4 length + 2 CARD16 number of buttons +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .75i 2.0i 3.0i --> +<!-- .ta .2i .75i 2.0i 3.0i --> +VALUATORINFO + 1 2 class id + 1 8+12n length + 1 n number of axes + 1 SETofDEVICEMODE mode + 4 CARD32 size of motion buffer + 12n LISTofAXISINFO valuator limits +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +AXISINFO + 4 CARD32 resolution + 4 CARD32 minimum value + 4 CARD32 maximum value +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +OpenDevice + 1 CARD8 input extension opcode + 1 3 OpenDevice opcode + 2 2 request length + 1 CARD8 device id + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 3 OpenDevice opcode + 2 CARD16 sequence number + 4 (n+p)/4 reply length + 1 CARD8 number of input classes + 23 unused + n LISTofINPUTCLASSINFO input class information + p unused, p=pad(n) +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + INPUTCLASSINFO + 1 CARD8 input class id + 0 KEY + 1 BUTTON + 2 VALUATOR + 3 FEEDBACK + 4 PROXIMITY + 5 FOCUS + 6 OTHER + 1 CARD8 event type base code for this class +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +CloseDevice + 1 CARD8 input extension opcode + 1 4 CloseDevice opcode + 2 2 request length + 1 CARD8 device id + 3 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SetDeviceMode + 1 CARD8 input extension opcode + 1 5 SetDeviceMode opcode + 2 2 request length + 1 CARD8 device id + 1 CARD8 mode + 2 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 5 SetDeviceMode opcode + 2 CARD16 sequence number + 4 0 reply length + 1 CARD8 status + 0 Success + 1 AlreadyGrabbed + 3 + first_error DeviceBusy + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SelectExtensionEvent + 1 CARD8 input extension opcode + 1 6 SelectExtensionEvent opcode + 2 3+n request length + 4 Window event window + 2 CARD16 count + 2 unused + 4n LISTofEVENTCLASS desired events +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetSelectedExtensionEvents + 1 CARD8 input extension opcode + 1 7 GetSelectedExtensionEvents opcode + 2 2 request length + 4 Window event window +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 7 GetSelecteExtensionEvents opcode + 2 CARD16 sequence number + 4 n + m reply length + 2 n this client count + 2 m all clients count + 20 unused + 4n LISTofEVENTCLASS this client list + 4m LISTofEVENTCLASS all clients list +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangeDeviceDontPropagateList + 1 CARD8 input extension opcode + 1 8 ChangeDeviceDontPropagateList opcode + 2 3+n request length + 4 Window event window + 2 n count of events + 1 mode + 0 AddToList + 1 DeleteFromList + 1 unused + 4n LISTofEVENTCLASS desired events +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceDontPropagateList + 1 CARD8 input extension opcode + 1 9 GetDeviceDontPropagateList opcode + 2 2 request length + 4 Window event window +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 9 GetDeviceDontPropagateList opcode + 2 CARD16 sequence number + 4 n reply length + 2 n count of events + 22 unused + 4n LISTofEVENTCLASS don't propagate list +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceMotionEvents + 1 CARD8 input extension opcode + 1 10 GetDeviceMotionEvents opcode + 2 4 request length + 4 TIMESTAMP start + 0 CurrentTime + 4 TIMESTAMP stop + 0 CurrentTime + 1 CARD8 device id + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 10 GetDeviceMotionEvents opcode + 2 CARD16 sequence number + 4 (m+1)n reply length + 4 n number of DEVICETIMECOORDs in events + 1 m number of valuators per event + 1 CARD8 mode of the device + 0 Absolute + 1 Relative + 18 unused + (4m+4)n LISTofDEVICETIMECOORD events +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + DEVICETIMECOORD + 4 TIMESTAMP time + 4m LISTofINT32 valuators +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangeKeyboardDevice + 1 CARD8 input extension opcode + 1 11 ChangeKeyboardDevice opcode + 2 2 request length + 1 CARD8 device id + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 11 ChangeKeyboardDevice opcode + 2 CARD16 sequence number + 4 0 reply length + 1 status + 0 Success + 1 AlreadyGrabbed + 2 DeviceFrozen + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangePointerDevice + 1 CARD8 input extension opcode + 1 12 ChangePointerDevice opcode + 2 2 request length + 1 CARD8 x-axis + 1 CARD8 y-axis + 1 CARD8 device id + 1 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 12 ChangePointerDevice opcode + 2 CARD16 sequence number + 4 0 reply length + 1 status + 0 Success + 1 AlreadyGrabbed + 2 DeviceFrozen + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GrabDevice + 1 CARD8 input extension opcode + 1 13 GrabDevice opcode + 2 5+n request length + 4 WINDOW grab-window + 4 TIMESTAMP time + 0 CurrentTime + 2 n count of events + 1 this-device-mode + 0 Synchronous + 1 Asynchronous + 1 other-devices-mode + 0 Synchronous + 1 Asynchronous + 1 BOOL owner-events + 1 CARD8 device id + 2 unused + 4n LISTofEVENTCLASS event list +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 13 GrabDevice opcode + 2 CARD16 sequence number + 4 0 reply length + 1 status + 0 Success + 1 AlreadyGrabbed + 2 InvalidTime + 3 NotViewable + 4 Frozen + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +UngrabDevice + 1 CARD8 input extension opcode + 1 14 UngrabDevice opcode + 2 3 request length + 4 TIMESTAMP time + 0 CurrentTime + 1 CARD8 device id + 3 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GrabDeviceKey + 1 CARD8 input extension opcode + 1 15 GrabDeviceKey opcode + 2 5+n request length + 4 WINDOW grab-window + 2 n count of events + 2 SETofKEYMASK modifiers + #x8000 AnyModifier + 1 CARD8 modifier device + #x0FF UseXKeyboard + 1 CARD8 grabbed device + 1 KEYCODE key + 0 AnyKey + 1 this-device-mode + 0 Synchronous + 1 Asynchronous + 1 other-devices-mode + 0 Synchronous + 1 Asynchronous + 1 BOOL owner-events + 2 unused + 4n LISTofEVENTCLASS event list +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +UngrabDeviceKey + 1 CARD8 input extension opcode + 1 16 UngrabDeviceKey opcode + 2 4 request length + 4 WINDOW grab-window + 2 SETofKEYMASK modifiers + #x8000 AnyModifier + 1 CARD8 modifier device + #x0FF UseXKeyboard + 1 KEYCODE key + 0 AnyKey + 1 CARD8 grabbed device + 3 unused + +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GrabDeviceButton + 1 CARD8 input extension opcode + 1 17 GrabDeviceButton opcode + 2 5+n request length + 4 WINDOW grab-window + 1 CARD8 grabbed device + 1 CARD8 modifier device + #x0FF UseXKeyboard + 2 n count of desired events + 2 SETofKEYMASK modifiers + 1 this-device-mode + 0 Synchronous + 1 Asynchronous + 1 other-device-mode + 0 Synchronous + 1 Asynchronous + 1 BUTTON button + 0 AnyButton + 1 BOOL owner-events + #x8000 AnyModifier + 2 unused + 4n LISTofEVENTCLASS event list +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +UngrabDeviceButton + 1 CARD8 input extension opcode + 1 18 UngrabDeviceButton opcode + 2 4 request length + 4 WINDOW grab-window + 2 SETofKEYMASK modifiers + #x8000 AnyModifier + 1 CARD8 modifier device + #x0FF UseXKeyboard + 1 BUTTON button + 0 AnyButton + 1 CARD8 grabbed device + 3 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +AllowDeviceEvents + 1 CARD8 input extension opcode + 1 19 AllowDeviceEvents opcode + 2 3 request length + 4 TIMESTAMP time + 0 CurrentTime + 1 mode + 0 AsyncThisDevice + 1 SyncThisDevice + 2 ReplayThisDevice + 3 AsyncOtherDevices + 4 AsyncAll + 5 SyncAll + 1 CARD8 device id + 2 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceFocus + 1 CARD8 input extension opcode + 1 20 GetDeviceFocus opcode + 2 2 request length + 1 CARD8 device + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 20 GetDeviceFocus opcode + 2 CARD16 sequence number + 4 0 reply length + 4 WINDOW focus + 0 None + 1 PointerRoot + 3 FollowKeyboard + 4 TIMESTAMP focus time + 1 revert-to + 0 None + 1 PointerRoot + 2 Parent + 3 FollowKeyboard + 15 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SetDeviceFocus + 1 CARD8 input extension opcode + 1 21 SetDeviceFocus opcode + 2 4 request length + 4 WINDOW focus + 0 None + 1 PointerRoot + 3 FollowKeyboard + 4 TIMESTAMP time + 0 CurrentTime + 1 revert-to + 0 None + 1 PointerRoot + 2 Parent + 3 FollowKeyboard + 1 CARD8 device + 2 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetFeedbackControl + 1 CARD8 input extension opcode + 1 22 GetFeedbackControl opcode + 2 2 request length + 1 CARD8 device id + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 22 GetFeedbackControl opcode + 2 CARD16 sequence number + 4 m/4 reply length + 2 n number of feedbacks supported + 22 unused + m LISTofFEEDBACKSTATE feedbacks +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + FEEDBACKSTATE KBDFEEDBACKSTATE, PTRFEEDBACKSTATE, INTEGERFEEDBACKSTATE, + STRINGFEEDBACKSTATE, BELLFEEDBACKSTATE, or LEDFEEDBACKSTATE +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + KBDFEEDBACKSTATE + 1 0 feedback class id + 1 CARD8 id of this feedback + 2 20 length + 2 CARD16 pitch + 2 CARD16 duration + 4 CARD32 led_mask + 4 CARD32 led_values + 1 global_auto_repeat + 0 Off + 1 On + 1 CARD8 click + 1 CARD8 percent + 1 unused + 32 LISTofCARD8 auto_repeats +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + PTRFEEDBACKSTATE + 1 0 feedback class id + 1 CARD8 id of this feedback + 2 12 length + 2 unused + 2 CARD16 acceleration-numerator + 2 CARD16 acceleration-denominator + 2 CARD16 threshold +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + INTEGERFEEDBACKSTATE + 1 0 feedback class id + 1 CARD8 id of this feedback + 2 16 length + 4 CARD32 resolution + 4 INT32 minimum value + 4 INT32 maximum value +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + STRINGFEEDBACKSTATE + 1 1 feedback class id + 1 CARD8 id of this feedback + 2 4n+8 length + 2 CARD16 max_symbols + 2 n number of keysyms supported + 4n LISTofKEYSYM key symbols supported +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + BELLFEEDBACKSTATE + 1 1 feedback class id + 1 CARD8 id of this feedback + 2 12 length + 1 CARD8 percent + 3 unused + 2 CARD16 pitch + 2 CARD16 duration +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + LEDFEEDBACKSTATE + 1 1 feedback class id + 1 CARD8 id of this feedback + 2 12 length + 4 CARD32 led_mask + 4 BITMASK led_values + #x0001 On + #x0002 Off +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangeFeedbackControl + 1 CARD8 input extension opcode + 1 23 ChangeFeedbackControl opcode + 2 3+n/4 request length + 4 BITMASK value-mask (has n bits set to 1) + #x0001 keyclick-percent + #x0002 bell-percent + #x0004 bell-pitch + #x0008 bell-duration + #x0010 led + #x0020 led-mode + #x0040 key + #x0080 auto-repeat-mode + #x0001 string + #x0001 integer + #x0001 acceleration-numerator + #x0002 acceleration-denominator + #x0004 acceleration-threshold + 1 CARD8 device id + 1 CARD8 feedback class id + 2 unused + n FEEDBACKCLASS +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + FEEDBACKCLASS KBDFEEDBACKCTL, PTRFEEDBACKCTL, INTEGERFEEDBACKCTL, + STRINGFEEDBACKCTL, BELLFEEDBACKCTL, or LEDFEEDBACKCTL +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + KBDFEEDBACKCTL + 1 0 feedback class id + 1 CARD8 id of this feedback + 2 20 length + 1 KEYCODE key + 1 auto-repeat-mode + 0 Off + 1 On + 2 Default + 1 INT8 key-click-percent + 1 INT8 bell-percent + 2 INT16 bell-pitch + 2 INT16 bell-duration + 4 CARD32 led_mask + 4 CARD32 led_values +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + PTRFEEDBACKCTL + 1 1 feedback class id + 1 CARD8 id of this feedback + 2 12 length + 2 unused + 2 INT16 numerator + 2 INT16 denominator + 2 INT16 threshold +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + STRINGCTL + 1 2 feedback class id + 1 CARD8 id of this feedback + 2 4n+8 length + 2 unused + 2 n number of keysyms to display + 4n LISTofKEYSYM list of key symbols to display +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + INTEGERCTL + 1 3 feedback class id + 1 CARD8 id of this feedback + 2 8 length + 4 INT32 integer to display +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + LEDCTL + 1 4 feedback class id + 1 CARD8 id of this feedback + 2 12 length + 4 CARD32 led_mask + 4 BITMASK led_values + #x0001 On + #x0002 Off +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + BELLCTL + 1 5 feedback class id + 1 CARD8 id of this feedback + 2 8 length + 1 INT8 percent + 3 unused + 2 INT16 pitch + 2 INT16 duration +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceKeyMapping + 1 CARD8 input extension opcode + 1 24 GetDeviceKeyMapping opcode + 2 2 request length + 1 CARD8 device + 1 KEYCODE first-keycode + 1 CARD8 count + 1 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .75i 2.0i 3.0i --> +<!-- .ta .2i .75i 2.0i 3.0i --> + => + 1 1 Reply + 1 24 GetDeviceKeyMapping opcode + 2 CARD16 sequence number + 4 nm reply length (m = count field from the request) + 1 n keysyms-per-keycode + 23 unused + 4nm LISTofKEYSYM keysyms +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .75i 2.0i 3.0i --> +<!-- .ta .2i .75i 2.0i 3.0i --> +ChangeDeviceKeyMapping + 1 CARD8 input extension opcode + 1 25 ChangeDeviceKeyMapping opcode + 2 2+nm request length + 1 CARD8 device + 1 KEYCODE first-keycode + 1 m keysyms-per-keycode + 1 n keycode-count + 4nm LISTofKEYSYM keysyms +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceModifierMapping + 1 CARD8 input extension opcode + 1 26 GetDeviceModifierMapping opcode + 2 2 request length + 1 CARD8 device + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 26 GetDeviceModifierMapping opcode + 2 CARD16 sequence number + 4 2n reply length + 1 n keycodes-per-modifier + 23 unused + 8n LISTofKEYCODE keycodes +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SetDeviceModifierMapping + 1 CARD8 input extension opcode + 1 27 SetDeviceModifier opcode + 2 2+2n request length + 1 CARD8 device + 1 n keycodes-per-modifier + 2 unused + 8n LISTofKEYCODE keycodes +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 27 SetDeviceModifierMapping opcode + 2 CARD16 sequence number + 4 0 reply length + 1 status + 0 Success + 1 Busy + 2 Failed + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceButtonMapping + 1 CARD8 input extension opcode + 1 28 GetDeviceButtonMapping opcode + 2 2 request length + 1 CARD8 device + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 28 GetDeviceButtonMapping opcode + 2 CARD16 sequence number + 4 (n+p)/4 reply length + 1 n number of elements in map list + 23 unused + n LISTofCARD8 map + p unused, p=pad(n) +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SetDeviceButtonMapping + 1 CARD8 input extension opcode + 1 29 SetDeviceButtonMapping opcode + 2 2+(n+p)/4 request length + 1 CARD8 device + 1 n length of map + 2 unused + n LISTofCARD8 map + p unused, p=pad(n) +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 29 SetDeviceButtonMapping opcode + 2 CARD16 sequence number + 4 0 reply length + 1 status + 0 Success + 1 Busy + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +QueryDeviceState + 1 CARD8 input extension opcode + 1 30 QueryDeviceState opcode + 2 2 request length + 1 CARD8 device + 3 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + => + 1 1 Reply + 1 30 QueryDeviceState opcode + 2 CARD16 sequence number + 4 m/4 reply length + 1 n number of input classes + 23 unused + m LISTofINPUTSTATE +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + INPUTSTATE KEYSTATE or BUTTONSTATE or VALUATORSTATE +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + KEYSTATE + 1 CARD8 key input class id + 1 36 length + 1 CARD8 num_keys + 1 unused + 32 LISTofCARD8 status of keys +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + BUTTONSTATE + 1 CARD8 button input class id + 1 36 length + 1 CARD8 num_buttons + 1 unused + 32 LISTofCARD8 status of buttons +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> + VALUATORSTATE + 1 CARD8 valuator input class id + 1 4n + 4 length + 1 n number of valuators + 1 mode + #x01 DeviceMode (0 = Relative, 1 = Absolute) + #x02 ProximityState (0 = InProximity, 1 = OutOfProximity) + 4n LISTofCARD32 status of valuators +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SendExtensionEvent + 1 CARD8 input extension opcode + 1 31 SendExtensionEvent opcode + 2 4 + 8n + m request length + 4 WINDOW destination + 1 CARD8 device + 1 BOOL propagate + 2 CARD16 eventclass count + 1 CARD8 num_events + 3 unused + 32n LISTofEVENTS events to send + 4m LISTofEVENTCLASS desired events +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceBell + 1 CARD8 input extension opcode + 1 32 DeviceBell opcode + 2 2 request length + 1 CARD8 device id + 1 CARD8 feedback id + 1 CARD8 feedback class + 1 INT8 percent +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +SetDeviceValuators + 1 CARD8 input extension opcode + 1 33 SetDeviceValuators opcode + 2 2 + n request length + 1 CARD8 device id + 1 CARD8 first valuator + 1 n number of valuators + 1 unused + 4n LISTofINT32 valuator values to set +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 33 SetDeviceValuators opcode + 2 CARD16 sequence number + 4 0 reply length + 1 CARD8 status + 0 Success + 1 AlreadyGrabbed + 23 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +GetDeviceControl + 1 CARD8 input extension opcode + 1 34 GetDeviceControl opcode + 2 2 request length + 2 CARD16 device control type + 1 CARD8 device id + 1 unused +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 34 GetDeviceControl opcode + 2 CARD16 sequence number + 4 n/4 reply length + 1 CARD8 status + 0 Success + 1 AlreadyGrabbed + 3 + first_error DeviceBusy + 23 unused + n DEVICESTATE +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DEVICESTATE DEVICERESOLUTIONSTATE +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DEVICERESOLUTIONSTATE + 2 0 control type + 2 8 + 12n length + 4 n num_valuators + 4n LISTOfCARD32 resolution values + 4n LISTOfCARD32 resolution min_values + 4n LISTOfCARD32 resolution max_values +</literallayout> +</para> +<para> +<!-- .LP --> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangeDeviceControl + 1 CARD8 input extension opcode + 1 35 ChangeDeviceControl opcode + 2 2+n/4 request length + 2 CARD16 control type + 1 CARD8 device id + 1 unused + n DEVICECONTROL +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DEVICECONTROL DEVICERESOLUTIONCTL +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DEVICERESOLUTIONCTL + 2 1 control type + 2 8 + 4n length + 1 CARD8 first_valuator + 1 n num_valuators + 2 unused + 4n LISTOfCARD32 resolution values +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 3.5i --> +<!-- .ta .2i .5i 1.5i 3.5i --> + => + 1 1 Reply + 1 35 ChangeDeviceControl opcode + 2 CARD16 sequence number + 4 0 reply length + 1 CARD8 status + 0 Success + 1 AlreadyGrabbed + 3 + first_error DeviceBusy + 23 unused +</literallayout> +<!-- .ps +2 --> +Events +<!-- .ps --> +</para> +<para> +<!-- .LP --> +DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease, +ProximityIn, ProximityOut, and DeviceStateNotify events may be followed by +zero or more DeviceValuator events. DeviceMotionNotify events will be +followed by one or more DeviceValuator events. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceValuator + 1 CARD8 code + 1 CARD8 device id + 2 CARD16 sequence number + 2 SETofKEYBUTMASK state + 1 n number of valuators this device reports + 1 m number of first valuator in this event + 24 LISTofINT32 valuators +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceKeyPress + 1 CARD8 code + 1 KEYCODE detail + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceKeyRelease + 1 CARD8 code + 1 KEYCODE detail + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceButtonPress + 1 CARD8 code + 1 BUTTON detail + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceButtonRelease + 1 CARD8 code + 1 BUTTON detail + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceMotionNotify + 1 CARD8 code + 1 detail + 0 Normal + 1 Hint + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceFocusIn + 1 CARD8 code + 1 detail + 0 Ancestor + 1 Virtual + 2 Inferior + 3 Nonlinear + 4 NonlinearVirtual + 5 Pointer + 6 PointerRoot + 7 None + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW event + 1 mode + 0 Normal + 1 Grab + 2 Ungrab + 3 WhileGrabbed + 1 CARD8 device id + 18 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceFocusOut + 1 CARD8 code + 1 detail + 0 Ancestor + 1 Virtual + 2 Inferior + 3 Nonlinear + 4 NonlinearVirtual + 5 Pointer + 6 PointerRoot + 7 None + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW event + 1 mode + 0 Normal + 1 Grab + 2 Ungrab + 3 WhileGrabbed + 1 CARD8 device id + 18 unused +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ProximityIn + 1 CARD8 code + 1 unused + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ProximityOut + 1 CARD8 code + 1 unused + 2 CARD16 sequence number + 4 TIMESTAMP time + 4 WINDOW root + 4 WINDOW event + 4 WINDOW child + 0 None + 2 INT16 root-x + 2 INT16 root-y + 2 INT16 event-x + 2 INT16 event-y + 2 SETofKEYBUTMASK state + 1 BOOL same-screen + 1 CARD8 device id + #x80 MORE_EVENTS follow +</literallayout> +</para> +<para> +<!-- .LP --> +DeviceStateNotify events may be immediately followed by zero or one +DeviceKeyStateNotify and/ or zero or more DeviceValuator events. +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceStateNotify + 1 CARD8 code + 1 CARD8 device id + #x80 MORE_EVENTS follow + 2 CARD16 sequence number + 4 TIMESTAMP time + 1 CARD8 num_keys + 1 CARD8 num_buttons + 1 CARD8 num_valuators + 1 CARD8 valuator mode and input classes reported + #x01 reporting keys + #x02 reporting buttons + #x04 reporting valuators + #x40 device mode (0 = Relative, 1 = Absolute) + #x80 proximity state (0 = InProximity, 1 = OutOfProximity) + 4 LISTofCARD8 first 32 keys (if reported) + 4 LISTofCARD8 first 32 buttons (if reported) + 12 LISTofCARD32 first 3 valuators (if reported) +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceKeyStateNotify + 1 CARD8 code + 1 CARD8 device id + #x80 MORE_EVENTS follow + 2 CARD16 sequence number + 28 LISTofCARD8 state of keys 33-255 +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceButtonStateNotify + 1 CARD8 code + 1 CARD8 device id + #x80 MORE_EVENTS follow + 2 CARD16 sequence number + 28 LISTofCARD8 state of buttons 33-255 +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceValuator + 1 CARD8 code + 1 CARD8 device id + 2 CARD16 sequence number + 2 SETofKEYBUTMASK state + 1 n number of valuators this device reports + 1 n number of first valuator in this event + 24 LISTofINT32 valuators +</literallayout> +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +DeviceMappingNotify + 1 CARD8 code + 1 CARD8 device id + 2 CARD16 sequence number + 1 request + 0 MappingModifier + 1 MappingKeyboard + 2 MappingPointer + 1 KEYCODE first-keycode + 1 CARD8 count + 1 unused + 4 TIMESTAMP time + 20 unused +</literallayout> +</para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .2i .5i 1.5i 2.5i --> +<!-- .ta .2i .5i 1.5i 2.5i --> +ChangeDeviceNotify + 1 CARD8 code + 1 CARD8 id of device specified on change request + 2 CARD16 sequence number + 4 TIMESTAMP time + 1 request + 0 NewPointer + 1 NewKeyboard + 23 unused +</literallayout> +<!-- .\" print Table of Contents --> +<!-- .if o .bp \" blank page to make count even --> +<!-- .bp 1 --> +<!-- .af PN i --> +<!-- .PX --> + +</appendix> diff --git a/specs/inputlib.xml b/specs/inputlib.xml new file mode 100644 index 0000000..526fede --- /dev/null +++ b/specs/inputlib.xml @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" + "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> + +<book id="inputlib"> + +<bookinfo> + <title>X11 Input Extension Protocol Specification</title> + <releaseinfo>X Version 11, Release 6.4</releaseinfo> + <authorgroup> + <author> + <firstname>Mark</firstname><surname>Patrick</surname> + <affiliation><orgname>Ardent Computer</orgname></affiliation> + </author> + <othercredit> + <firstname>George</firstname><surname>Sachs</surname> + <affiliation><orgname>Hewlett-Packard</orgname></affiliation> + </othercredit> + </authorgroup> + <copyright><year>1989</year><holder>Hewlett-Packard Company and Ardent Computer</holder></copyright> + <copyright><year>1990</year><holder>Hewlett-Packard Company and Ardent Computer</holder></copyright> + <copyright><year>1991</year><holder>Hewlett-Packard Company and Ardent Computer</holder></copyright> + + <copyright><year>1989</year><holder>X Consortium</holder></copyright> + <copyright><year>1990</year><holder>X Consortium</holder></copyright> + <copyright><year>1991</year><holder>X Consortium</holder></copyright> + <copyright><year>1992</year><holder>X Consortium</holder></copyright> + + <releaseinfo>1.0</releaseinfo> + <productnumber>X Version 11, Release 6.4</productnumber> + +<legalnotice> + +<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. +</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 Open Group 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. +</para> + +<para>X Window System is a trademark of X Consortium, Inc.</para> + +</legalnotice> +</bookinfo> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="library.xml"/> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="encoding.xml"/> +</book> + diff --git a/specs/library.xml b/specs/library.xml new file mode 100644 index 0000000..f399800 --- /dev/null +++ b/specs/library.xml @@ -0,0 +1,8559 @@ +<chapter><title>Input Extension</title> +<sect1 id="Input_Extension_Overview"> +<title>Overview</title> +<!-- .XS --> +<!-- (SN Input Extension Overview --> +<!-- .XE --> +<para> +<!-- .LP --> +This document describes an extension to +the X11 server. The purpose of this extension is to support the use +of additional input devices beyond the pointer and keyboard devices +defined by the core X protocol. This first section gives an overview +of the input extension. The following sections correspond to +chapters 9, 10, and 11, ``Window and Session Manager Functions'', +``Events'', and ``Event Handling Functions'' of the +``Xlib - C Language Interface'' manual +and describe how to use the input device extension. +</para> +<sect2 id="Design_Approach"> +<title>Design Approach</title> +<!-- .XS --> +<!-- (SN Design Approach --> +<!-- .XE --> +<para> +<!-- .LP --> +The design approach of the extension is to define functions +and events analogous to the core functions and events. +This allows extension input devices and events to be individually +distinguishable from each other and from the core input devices and events. +These functions and events make use of a device identifier and support the +reporting of <emphasis remap='I'>n</emphasis>-dimensional motion data as well as other data that +is not currently reportable via the core input events. +</para> +</sect2> +<sect2 id="Core_Input_Devices"> +<title>Core Input Devices</title> +<!-- .XS --> +<!-- (SN Core Input Devices --> +<!-- .XE --> +<para> +<!-- .LP --> +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> +<!-- .LP --> +The X keyboard is used to generate input that client programs can detect. +</para> +<para> +<!-- .LP --> +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 +<function>( KeyPress ,</function> +<function>KeyRelease ,</function> +<function>ButtonPress ,</function> +<function>ButtonRelease ,</function> +and +<function>MotionNotify )</function> +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>. +<!-- .NT --> +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.'' +<!-- .NE --> +</para> +<para> +<!-- .LP --> +Selection of the physical devices to be initially used by the server as the +core devices is left implementation dependent. Functions 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> +<!-- .XS --> +<!-- (SN Extension Input Devices --> +<!-- .XE --> +<para> +<!-- .LP --> +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. Input events from +these devices are of extension types +<function>( DeviceKeyPress ,</function> +<function>DeviceKeyRelease ,</function> +<function>DeviceButtonPress ,</function> +<function>DeviceButtonRelease ,</function> +<function>DeviceMotionNotify ,</function> +and so on) and contain +a device identifier so that events of the same type coming from different +input devices can be distinguished. +</para> +<para> +<!-- .LP --> +Extension input events are not limited in size by the size of the server +32-byte wire events. Extension input events +may be constructed by the server sending as many +wire-sized events as necessary to return the information required for +that event. +The library event reformatting routines +are responsible for combining these into one or more client XEvents. +</para> +<para> +<!-- .LP --> +Any input device that generates key, button, or motion data may be used as +an extension input device. +Extension input devices may have zero or more keys, zero or more buttons, +and may report zero 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> +<!-- .LP --> +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='I'>input device classes</emphasis>. Server implementors may add new +classes of input devices without changing the protocol requests. +</para> +<para> +<!-- .LP --> +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> +<sect3 id="Input_Device_Classes"> +<title>Input Device Classes</title> +<!-- .XS --> +<!-- (SN Input Device Classes --> +<!-- .XE --> +<para> +<!-- .LP --> +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 functions. The following input device classes are currently +defined: +<variablelist> + <varlistentry> + <term>KEY</term> + <listitem> + <para> +The device reports key events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>BUTTON</term> + <listitem> + <para> +The device reports button events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>VALUATOR</term> + <listitem> + <para> +The device reports valuator data in motion events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>PROXIMITY</term> + <listitem> + <para> +The device reports proximity events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>FOCUS</term> + <listitem> + <para> +The device can be focused. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>FEEDBACK</term> + <listitem> + <para> +The device supports feedbacks. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Additional classes may be added in the future. +Functions that support multiple input classes, such as the +<function>XListInputDevices</function> +function that lists all available input devices, +organize the data they return by input class. Client programs that +use these functions 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 functions to be recompiled. +</para> +</sect3> +</sect2> +<sect2 id="Using_Extension_Input_Devices"> +<title>Using Extension Input Devices</title> +<!-- .XS --> +<!-- (SN Using Extension Input Devices --> +<!-- .XE --> +<para> +<!-- .LP --> +A client that wishes to access an input device does so through the library +functions defined in the following sections. A typical sequence of requests +that a client would make is as follows: +</para> +<itemizedlist> + <listitem> + <para> +<function>XListInputDevices</function> +- lists all of the available input devices. From the +information returned by this request, determine whether the desired input +device is attached to the server. For a description of the +<function>XListInputDevices</function> +request, see the section entitled ``Listing Available Devices.'' + </para> + </listitem> + <listitem> + <para> +<function>XOpenDevice</function> +- requests that the server open the device for access by this client. +This request returns an +<function>XDevice</function> +structure that is used +by most other input extension requests to identify the specified device. +For a description of the +<function>XOpenDevice</function> +request, see the section entitled ``Enabling and Disabling Extension Devices.'' + </para> + </listitem> + <listitem> + <para> +Determine the event types and event classes needed to select the desired +input extension events, and identify them when they are received. +This is done via macros whose name corresponds to the desired event, for +example, +<function>DeviceKeyPress .</function> +For a description of these macros, +see the section entitled ``Selecting Extension Device Events.'' + </para> + </listitem> + <listitem> + <para> +<function>XSelectExtensionEvent</function> +- selects the desired events from the server. +For a description of the +<function>XSelextExtensionEvent</function> +request, see the section entitled ``Selecting Extension Device Events.'' + </para> + </listitem> + <listitem> + <para> +<function>XNextEvent</function> +- receives the next available event. This is the core +<function>XNextEvent</function> +function provided by the standard X libarary. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Other requests are defined to grab and focus extension devices, to +change their key, button, or modifier mappings, to control the +propagation of input extension events, to get motion history from an +extension device, and to send input extension events to another client. +These functions are described in the following sections. +</para> +</sect2> +</sect1> +<sect1 id="Library_Extension_Requests"> +<title>Library Extension Requests</title> +<!-- .XS --> +<!-- (SN Library Extension Requests --> +<!-- .XE --> +<para> +<!-- .LP --> +Extension input devices are accessed by client programs through the +use of new protocol requests. +The following requests are provided as extensions to Xlib. Constants +and structures referenced by these functions may be found in the +files <function><X11/extensions/XI.h></function> and <function><X11/extensions/XInput.h></function>, +which are attached to this document as +Appendix A.<!-- xref --> +</para> +<para> +<!-- .LP --> +The library will return <function>NoSuchExtension</function> if an extension request +is made to a server that does not support the input extension. +</para> +<para> +<!-- .LP --> +Input extension requests cannot be used to access the X keyboard and +X pointer devices. +</para> +<sect2 id="Window_Manager_Functions"> +<title>Window Manager Functions</title> +<!-- .XS --> +<!-- (SN Window Manager Functions --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses the following X Input Extension Window Manager topics: +</para> +<itemizedlist> + <listitem> + <para> +Changing the core devices + </para> + </listitem> + <listitem> + <para> +Event synchronization and core grabs + </para> + </listitem> + <listitem> + <para> +Extension active grabs + </para> + </listitem> + <listitem> + <para> +Passively grabbing a key + </para> + </listitem> + <listitem> + <para> +Passively grabbing a button + </para> + </listitem> + <listitem> + <para> +Thawing a device + </para> + </listitem> + <listitem> + <para> +Controlling device focus + </para> + </listitem> + <listitem> + <para> +Controlling device feedback + </para> + </listitem> + <listitem> + <para> +Ringing a bell on an input device + </para> + </listitem> + <listitem> + <para> +Controlling device encoding + </para> + </listitem> + <listitem> + <para> +Controlling button mapping + </para> + </listitem> + <listitem> + <para> +Obtaining the state of a device + </para> + </listitem> +</itemizedlist> +<sect3 id="Changing_the_Core_Devices"> +<title>Changing the Core Devices</title> +<!-- .XS --> +<!-- (SN Changing the Core Devices --> +<!-- .XE --> + +<para> +<!-- .LP --> +These functions are provided to change which physical device is used +as the X pointer or X keyboard. +</para> +<!-- .NT --> +<note><para> +Using these functions may change the characteristics of the core devices. +The new pointer device may have a different number of buttons from the +old one, 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 indices into that array. Changing the core devices could cause +such client programs to behave improperly or to terminate abnormally +if they ignore the +<function>ChangeDeviceNotify</function> +event generated by these requests. +</para></note> +<!-- .NE --> + +<para> +<!-- .LP --> +These functions change the X keyboard or X pointer device and generate an +<function>XChangeDeviceNotify</function> +event and a +<function>MappingNotify</function> +event. +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> +<!-- .LP --> +These requests fail and return +<function>AlreadyGrabbed</function> +if either the specified +device or the core device it would replace are grabbed by some other client. +They fail and return +<function>GrabFrozen</function> +if either device is frozen by the active grab of another client. +</para> +<para> +<!-- .LP --> +These requests fail with a +<function>BadDevice</function> +error if the specified device is invalid, has not previously been opened via +<function>XOpenDevice ,</function> +or is +not supported as a core device by the server implementation. +</para> +<para> +<!-- .LP --> +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 +<function>ChangeDevice</function> +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 +<function>XCloseDevice</function> +request to close the new core device will fail with a +<function>BadDevice</function> +error. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To change which physical device is used as the X keyboard, use the +<function>XChangeKeyboardDevice</function> +function. +The specified device must support input class +<function>Keys</function> +(as reported in the +<function>ListInputDevices</function> +request) or the request will fail with a +<function>BadMatch</function> +error. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XChangeKeyboardDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If no error occurs, +<function>XChangeKeyboardDevice</function> +returns +<function>Success .</function> +A +<function>ChangeDeviceNotify</function> +event with the request field set to +<function>NewKeyboard</function> +is sent to all clients selecting that event. +A +<function>MappingNotify</function> +event with the request field set to +<function>MappingKeyboard</function> +is sent to all clients. +The requested device becomes the X keyboard, and the old keyboard becomes +available as an extension input device. +The focus state of the new keyboard is the same as +the focus state of the old X keyboard. +</para> +<para> +<!-- .LP --> +<function>XChangeKeyboardDevice</function> +can generate +<function>AlreadyGrabbed ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>GrabFrozen</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To change which physical device is used as the X pointer, +use the +<function>XChangePointerDevice</function> +function. +The specified device must support input class +<function>Valuators</function> +(as reported in the +<function>XListInputDevices</function> +request) and report at least two axes of motion, +or the request will fail with a +<function>BadMatch</function> +error. +If the specified device reports more than two axes, the two specified in +the xaxis and yaxis arguments will be used. Data from other +valuators on the device will be ignored. +</para> +<para> +<!-- .LP --> +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 +<function>BadDevice</function> +error. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XChangePointerDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> xaxis</parameter></paramdef> + <paramdef>int<parameter> yaxis</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>xaxis</emphasis> + </term> + <listitem> + <para> +Specifies the zero-based index of the axis to be used as the x-axis of the +pointer device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>yaxis</emphasis> + </term> + <listitem> + <para> +Specifies the zero-based index of the axis to be used as the y-axis of the +pointer device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +If no error occurs, +<function>XChangePointerDevice</function> +returns +<function>Success .</function> +A +<function>ChangeDeviceNotify</function> +event with the request field set to +<function>NewPointer</function> +is sent to all clients selecting that event. +A +<function>MappingNotify</function> +event with the request field set to +<function>MappingPointer</function> +is sent to all clients. +The requested device becomes the X pointer, and the old pointer becomes +available as an extension input device. +</para> +<para> +<!-- .LP --> +<function>XChangePointerDevice</function> +can generate +<function>AlreadyGrabbed ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>GrabFrozen</function> +errors. +</para> +</sect3> +<sect3 id="Event_Synchronization_and_Core_Grabs"> +<title>Event Synchronization and Core Grabs</title> +<!-- .XS --> +<!-- (SN Event Synchronization and Core Grabs --> +<!-- .XE --> +<para> +<!-- .LP --> +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> +<!-- .LP --> +The core grab requests require a pointer_mode and keyboard_mode +argument. The meaning of these modes is changed by the input extension. +For the +<function>XGrabPointer</function> +and +<function>XGrabButton</function> +requests, pointer_mode controls synchronization of the pointer device, +and keyboard_mode controls the synchronization of all other input devices. +For the +<function>XGrabKeyboard</function> +and +<function>XGrabKey</function> +requests, pointer_mode controls the synchronization +of all input devices, except the X keyboard, while keyboard_mode controls +the synchronization of the keyboard. When using one of the core grab +requests, the synchronization of extension devices +is controlled by the mode specified for the device not being grabbed. +</para> +</sect3> +<sect3 id="Extension_Active_Grabs"> +<title>Extension Active Grabs</title> +<!-- .XS --> +<!-- (SN Extension Active Grabs --> +<!-- .XE --> +<para> +<!-- .LP --> +Active grabs of +extension devices are supported via the +<function>XGrabDevice</function> +function in the same way that core devices are grabbed using the core +<function>XGrabKeyboard</function> +function, except that an extension input device +is passed as a function parameter. +The +<function>XUngrabDevice</function> +function allows a previous active grab for an extension device to be released. +</para> +<para> +<!-- .LP --> +Passive grabs of buttons and keys on extension devices are supported +via the +<function>XGrabDeviceButton</function> +and +<function>XGrabDeviceKey</function> +functions. +These passive grabs are released via the +<function>XUngrabDeviceKey</function> +and +<function>XUngrabDeviceButton</function> +functions. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To grab an extension device, use the +<function>XGrabDevice</function> +function. +The device must have previously been opened using the +<function>XOpenDevice</function> +function. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGrabDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Window<parameter> grab_window</parameter></paramdef> + <paramdef>Bool<parameter> owner_events</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> + <paramdef>XEventClass<parameter> *event_list</parameter></paramdef> + <paramdef>int<parameter> this_device_mode</parameter></paramdef> + <paramdef>int<parameter> other_device_mode</parameter></paramdef> + <paramdef>Time<parameter> time</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + "<emphasis remap='I'>display</emphasis>" + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>grab_window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of a window associated with the device specified above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>owner_events</emphasis> + </term> + <listitem> + <para> +Specifies a boolean value of either +<function>True</function> +or +<function>False .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the event_list array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_list</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a list of event classes that indicate which events +the client wishes to receive. +These event classes must have been obtained +using the device being grabbed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>this_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from this device. You can pass one +of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>other_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from all other devices. You can pass one +of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. This may be either a timestamp expressed in +milliseconds or +<function>CurrentTime .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGrabDevice</function> +actively grabs an extension input device and generates +<function>DeviceFocusIn</function> +and +<function>DeviceFocusOut</function> +events. +Further input events from this device are reported only to the grabbing client. +This function overrides any previous active grab by this client for this device. +</para> +<para> +<!-- .LP --> +The event_list parameter is a pointer to a list of event classes. This list +indicates which events the client wishes to receive while the grab is active. +If owner_events is +<function>False ,</function> +input events from this device are reported with respect to +grab_window and are reported only if specified in event_list. +If owner_events is +<function>True ,</function> +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 specified in event_list. +</para> +<para> +<!-- .LP --> +The this_device_mode argument controls the further processing +of events from this device, and the other_device_mode argument controls +the further processing of input events from all other devices. +</para> +<itemizedlist> + <listitem> + <para> +If the this_device_mode argument is +<function>GrabModeAsync ,</function> +device event processing continues +normally; if the device is currently frozen by this client, then +processing of device events is resumed. +If the this_device_mode argument is +<function>GrabModeSync ,</function> +the state of the grabbed device +(as seen by client applications) appears to freeze, +and no further device events are generated by the server until the +grabbing client issues a releasing +<function>XAllowDeviceEvents</function> +call 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> + </listitem> + <listitem> + <para> +If the other_device_mode is +<function>GrabModeAsync ,</function> +event processing from other input devices is unaffected +by activation of the grab. +If other_device_mode is +<function>GrabModeSync ,</function> +the state of all devices except the grabbed device +(as seen by client applications) appears to freeze, and no further +events are generated by the server until the grabbing client issues a +releasing +<function>XAllowEvents</function> +or +<function>XAllowDeviceEvents</function> +call or until the device grab is released. +Actual events are not lost +while the other devices are frozen; they are simply queued for later +processing. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>XGrabDevice</function> +fails on the following conditions: +</para> +<itemizedlist> + <listitem> + <para> +If the device is actively grabbed by some other client, it returns +<function>AlreadyGrabbed .</function> + </para> + </listitem> + <listitem> + <para> +If grab_window is not viewable, it returns +<function>GrabNotViewable .</function> + </para> + </listitem> + <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, it returns +<function>GrabInvalidTime .</function> +Otherwise, +the last-grab-time for the specified device is set +to the specified time and +<function>CurrentTime</function> +is replaced by the current X server time. + </para> + </listitem> + <listitem> + <para> +If the device is frozen by an active grab of another client, it returns +<function>GrabFrozen .</function> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +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> +<!-- .LP --> +<function>XGrabDevice</function> +can generate +<function>BadClass ,</function> +<function>BadDevice ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To release a grab of an extension device, use the +<function>XUngrabDevice</function> +function. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XUngrabDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Time<parameter> time</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. This may be either a timestamp expressed in +milliseconds, or +<function>CurrentTime .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XUngrabDevice</function> +allows a client to release an extension input device and any +queued events if this client has it grabbed from either +<function>XGrabDevice</function> +or +<function>XGrabDeviceKey .</function> +If any other devices are frozen by the grab, +<function>XUngrabDevice</function> +thaws them. +This function does not release the device and any +queued events if the specified time is earlier than the last-device-grab +time or is later than the current X server time. It also generates +<function>DeviceFocusIn</function> +and +<function>DeviceFocusOut</function> +events. The X server automatically performs an +<function>XUngrabDevice</function> +if the event window for an active device grab becomes not viewable +or if the client terminates without releasing the grab. +</para> +<para> +<!-- .LP --> +<function>XUngrabDevice</function> +can generate +<function>BadDevice</function> +errors. +</para> +</sect3> +<sect3 id="Passively_Grabbing_a_Key"> +<title>Passively Grabbing a Key</title> +<!-- .XS --> +<!-- (SN Passively Grabbing a Key --> +<!-- .XE --> +<para> +<!-- .LP --> +To passively grab a single key on an extension device, use +<function>XGrabDeviceKey .</function> +That device must have previously been opened using the +<function>XOpenDevice</function> +function, or the request will fail with a +<function>BadDevice</function> +error. +If the specified device does not support input class +<function>Keys ,</function> +the request will fail with a +<function>BadMatch</function> +error. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGrabDeviceKey</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> keycode</parameter></paramdef> + <paramdef>unsignedint<parameter> modifiers</parameter></paramdef> + <paramdef>XDevice<parameter> *modifier_device</parameter></paramdef> + <paramdef>Window<parameter> grab_window</parameter></paramdef> + <paramdef>Bool<parameter> owner_events</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> + <paramdef>XEventClass<parameter> *event_list</parameter></paramdef> + <paramdef>int<parameter> this_device_mode</parameter></paramdef> + <paramdef>int<parameter> other_device_mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keycode</emphasis> + </term> + <listitem> + <para> +Specifies the keycode of the key that is to be grabbed. You can pass +either the keycode or +<function>AnyKey .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks. This mask is the bitwise inclusive OR +of these keymask bits: +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask ,</function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +and +<function>Mod5Mask .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + + </term> + <listitem> + <para> +You can also pass +<function>AnyModifier ,</function> +which is equivalent to issuing the grab key request +for all possible modifier combinations (including the combination +of no modifiers). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifier_device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose modifiers are to be used. If NULL is +specified, the core X keyboard is used as the modifier_device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>grab_window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of a window associated with the device specified above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>owner_events</emphasis> + </term> + <listitem> + <para> +Specifies a boolean value of either +<function>True</function> +or +<function>False .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the event_list array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_list</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to a list of event classes that indicate which events +the client wishes to receive. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>this_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from this device. +You can pass one of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>other_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from all other devices. +You can pass one of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGrabDeviceKey</function> +is analogous to the core +<function>XGrabKey</function> +function. It creates an +explicit passive grab for a key on an extension device. +The +<function>XGrabDeviceKey</function> +function establishes a passive grab on a device. +Consequently, in the future, +</para> +<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 +<function>XGrabDevice ,</function> +the last-device-grab time is set to the time at which the key was pressed +(as transmitted in the +<function>DeviceKeyPress</function> +event), and the +<function>DeviceKeyPress</function> +event is reported. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The interpretation of the remaining arguments is as for +<function>XGrabDevice .</function> +The active grab is terminated automatically when the logical state of the +device has the specified key released +(independent of the logical state of the modifier keys). +</para> +<para> +<!-- .LP --> +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> +<!-- .LP --> +A modifier of +<function>AnyModifier</function> +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 +<function>AnyKey</function> +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 +information returned by the +<function>XListInputDevices</function> +function. +If it is not within that range, +<function>XGrabDeviceKey</function> +generates a +<function>BadValue</function> +error. +</para> +<para> +<!-- .LP --> +<function>XGrabDeviceKey</function> +generates a +<function>BadAccess</function> +error if some other client has issued a +<function>XGrabDeviceKey</function> +with the same device and key combination on the same window. +When using +<function>AnyModifier</function> +or +<function>AnyKey ,</function> +the request fails completely and the X server generates a +<function>BadAccess</function> +error, and no grabs are established if there is a conflicting grab +for any combination. +</para> +<para> +<!-- .LP --> +<function>XGrabDeviceKey</function> +returns +<function>Success</function> +upon successful completion of the request. +</para> +<para> +<!-- .LP --> +<function>XGrabDeviceKey</function> +can generate +<function>BadAccess ,</function> +<function>BadClass ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To release a passive grab of a single key on an extension device, use +<function>XUngrabDeviceKey .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XUngrabDeviceKey</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> keycode</parameter></paramdef> + <paramdef>unsignedint<parameter> modifiers</parameter></paramdef> + <paramdef>XDevice<parameter> *modifier_device</parameter></paramdef> + <paramdef>Window<parameter> ungrab_window</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keycode</emphasis> + </term> + <listitem> + <para> +Specifies the keycode of the key that is to be ungrabbed. You can pass +either the keycode or +<function>AnyKey .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks. This mask is the bitwise inclusive OR +of these keymask bits: +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask , </function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +and +<function>Mod5Mask .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + + </term> + <listitem> + <para> +You can also pass +<function>AnyModifier ,</function> +which is equivalent to issuing the ungrab key +request for all possible modifier combinations (including the combination +of no modifiers). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifier_device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose modifiers are to be used. If NULL is +specified, the core X keyboard is used as the modifier_device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ungrab_window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of a window associated with the device specified above. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XUngrabDeviceKey</function> +is analogous to the core +<function>XUngrabKey</function> +function. It releases an explicit passive grab for a key +on an extension input device. +</para> +<para> +<!-- .LP --> +<function>XUngrabDeviceKey</function> +can generate +<function>BadAlloc ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Passively_Grabbing_a_Button"> +<title>Passively Grabbing a Button</title> +<!-- .XS --> +<!-- (SN Passively Grabbing a Button --> +<!-- .XE --> +<para> +<!-- .LP --> +To establish a passive grab for a single button on an extension device, use +<function>XGrabDeviceButton .</function> +The specified device must have previously been opened using the +<function>XOpenDevice</function> +function, or the request will fail with a +<function>BadDevice</function> +error. If the specified device does not support input class +<function>Buttons ,</function> +the request will fail with a +<function>BadMatch</function> +error. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGrabDeviceButton</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>unsignedint<parameter> button</parameter></paramdef> + <paramdef>unsignedint<parameter> modifiers</parameter></paramdef> + <paramdef>XDevice*modifier_device<parameter> </parameter></paramdef> + <paramdef>Window<parameter> grab_window</parameter></paramdef> + <paramdef>Bool<parameter> owner_events</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> + <paramdef>XEventClass<parameter> *event_list</parameter></paramdef> + <paramdef>int<parameter> this_device_mode</parameter></paramdef> + <paramdef>int<parameter> other_device_mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>button</emphasis> + </term> + <listitem> + <para> +Specifies the code of the button that is to be grabbed. You can pass +either the button or +<function>AnyButton .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks. This mask is the bitwise inclusive OR +of these keymask bits: +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask , </function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +and +<function>Mod5Mask .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + + </term> + <listitem> + <para> +You can also pass +<function>AnyModifier ,</function> +which is equivalent to issuing the grab request +for all possible modifier combinations (including the combination +of no modifiers). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifier_device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose modifiers are to be used. If NULL is +specified, the core X keyboard is used as the modifier_device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>grab_window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of a window associated with the device specified above. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>owner_events</emphasis> + </term> + <listitem> + <para> +Specifies a boolean value of either +<function>True</function> +or +<function>False .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the event_list array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_list</emphasis> + </term> + <listitem> + <para> +Specifies a list of event classes that indicates which device events are to be +reported to the client. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>this_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from this device. You can pass one +of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>other_device_mode</emphasis> + </term> + <listitem> + <para> +Controls further processing of events from all other devices. You can pass one +of these constants: +<function>GrabModeSync</function> +or +<function>GrabModeAsync .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGrabDeviceButton </function> +is analogous to the core +<function>XGrabButton</function> +function. +It creates an explicit passive grab for a button on an extension input device. +Because 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 +<function>XOpenDevice</function> +function. +</para> +<para> +<!-- .LP --> +The +<function>XGrabDeviceButton</function> +function establishes a passive grab on a device. +Consequently, in the future, +</para> +<itemizedlist> + <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> + <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 button/key combination does not +exist on any ancestor of the grab window, + </para> + </listitem> + <listitem> + <para> +THEN the device is actively grabbed, as for +<function>XGrabDevice ,</function> +the last-grab time is set to the time at which the button was pressed +(as transmitted in the +<function>DeviceButtonPress</function> +event), and the +<function>DeviceButtonPress</function> +event is reported. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The interpretation of the remaining arguments is as for +<function>XGrabDevice .</function> +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> +<!-- .LP --> +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> +<!-- .LP --> +A modifier of +<function>AnyModifier</function> +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 +<function>AnyButton</function> +is equivalent to issuing +the request for all possible buttons. +Otherwise, it is not required that the +specified button be assigned to a physical button. +</para> +<para> +<!-- .LP --> +<function>XGrabDeviceButton</function> +generates a +<function>BadAccess</function> +error if some other client has issued a +<function>XGrabDeviceButton</function> +with the same device and button combination on the same window. +When using +<function>AnyModifier</function> +or +<function>AnyButton ,</function> +the request fails completely and the X server generates a +<function>BadAccess</function> +error and no grabs are +established if there is a conflicting grab for any combination. +</para> +<para> +<!-- .LP --> +<function>XGrabDeviceButton</function> +can generate +<function>BadAccess , </function> +<function>BadClass ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To release a passive grab of a button on an extension device, use +<function>XUngrabDeviceButton .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XUngrabDeviceButton</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>unsignedint<parameter> button</parameter></paramdef> + <paramdef>unsignedint<parameter> modifiers</parameter></paramdef> + <paramdef>XDevice<parameter> *modifier_device</parameter></paramdef> + <paramdef>Window<parameter> ungrab_window</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>button</emphasis> + </term> + <listitem> + <para> +Specifies the code of the button that is to be ungrabbed. You can pass +either a button or +<function>AnyButton .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifiers</emphasis> + </term> + <listitem> + <para> +Specifies the set of keymasks. This mask is the bitwise inclusive OR +of these keymask bits: +<function>ShiftMask ,</function> +<function>LockMask ,</function> +<function>ControlMask , </function> +<function>Mod1Mask ,</function> +<function>Mod2Mask ,</function> +<function>Mod3Mask ,</function> +<function>Mod4Mask ,</function> +and +<function>Mod5Mask .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + + </term> + <listitem> + <para> +You can also pass +<function>AnyModifier ,</function> +which is equivalent to issuing the ungrab key +request for all possible modifier combinations (including the combination +of no modifiers). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modifier_device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose modifiers are to be used. If NULL is +specified, the core X keyboard is used as the modifier_device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ungrab_window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of a window associated with the device specified above. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XUngrabDeviceButton </function> +is analogous to the core +<function>XUngrabButton</function> +function. It releases an explicit passive grab for a button +on an extension device. +That device must have previously been opened using the +<function>XOpenDevice</function> +function, or a +<function>BadDevice</function> +error will result. +</para> +<para> +<!-- .LP --> +A modifier of +<function>AnyModifier</function> +is equivalent to issuing the request for all +possible modifier combinations (including the combination of no +modifiers). +</para> +<para> +<!-- .LP --> +<function>XUngrabDeviceButton </function> +can generate +<function>BadAlloc , </function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Thawing_a_Device"> +<title>Thawing a Device</title> +<!-- .XS --> +<!-- (SN Thawing a Device --> +<!-- .XE --> +<para> +<!-- .LP --> +To allow further events to be processed when a device has been frozen, use +<function>XAllowDeviceEvents .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XAllowDeviceEvents</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> event_mode</parameter></paramdef> + <paramdef>Time<parameter> time</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_mode</emphasis> + </term> + <listitem> + <para> +Specifies the event mode. You can pass one of these constants: +<function>AsyncThisDevice ,</function> +<function>SyncThisDevice ,</function> +<function>AsyncOtherDevices ,</function> +<function>ReplayThisDevice ,</function> +<function>AsyncAll ,</function> +or +<function>SyncAll .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. This may be either a timestamp expressed in +milliseconds, or +<function>CurrentTime .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XAllowDeviceEvents</function> +releases some queued events if the client has caused a device to freeze. +It has no effect if the specified time is earlier than the last-grab +time of the most recent active grab for the client and device, +or if the specified time is later than the current X server time. +The following describes the processing that occurs depending on what constant +you pass to the event_mode argument: +</para> +<itemizedlist> + <listitem> + <para> +<function>AsyncThisDevice</function> + </para> + </listitem> + <listitem> + <para> +If the specified device is frozen by the client, event processing for that +continues as usual. If the device is frozen multiple times by the client on +behalf of multiple separate grabs, +<function>AsyncThisDevice</function> +thaws for all. +<function>AsyncThisDevice</function> +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> + <listitem> + <para> +<function>SyncThisDevice</function> + </para> + </listitem> + <listitem> + <para> +If the specified device is frozen and actively grabbed by the client, +event processing for that device continues normally until the next +key or button 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. +<function>SyncThisDevice</function> +has no effect if the specified device is not frozen by the client +or is not grabbed by the client. + </para> + </listitem> + <listitem> + <para> +<function>ReplayThisDevice</function> + </para> + </listitem> + <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 +<function>GrabDeviceButton</function> +or from a previous +<function>AllowDeviceEvents</function> +with mode +<function>SyncThisDevice , </function> +but not from a +<function>Grab ),</function> +the grab is released and that event is completely reprocessed. +This time, however, the request ignores any passive grabs at or above +(toward 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> + <listitem> + <para> +<function>AsyncOtherDevices</function> + </para> + </listitem> + <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, +<function>AsyncOtherDevices</function> +``thaws'' for all. +<function>AsyncOtherDevices</function> +has no effect if the devices are not frozen by the client, +but those devices need not be grabbed by the client. + </para> + </listitem> + <listitem> + <para> +<function>SyncAll</function> + </para> + </listitem> + <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, +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). +<function>SyncAll</function> +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, +<function>SyncAll</function> +"thaws" for both (but a subsequent freeze for +<function>SyncAll</function> +will freeze each device only once). + </para> + </listitem> + <listitem> + <para> +<function>AsyncAll</function> + </para> + </listitem> + <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, +<function>AsyncAll</function> +``thaws ''for all. +If any device is frozen twice by the client on behalf of two separate grabs, +<function>AsyncAll</function> +``thaws'' for both. +<function>AsyncAll</function> +has no effect unless all devices are frozen by the client. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +<function>AsyncThisDevice ,</function> +<function>SyncThisDevice ,</function> +and +<function>ReplayThisDevice </function> +have no effect on the processing of events from the remaining devices. +<function>AsyncOtherDevices</function> +has no effect on the processing of events from the specified device. +When the event_mode is +<function>SyncAll</function> +or +<function>AsyncAll ,</function> +the device parameter is ignored. +</para> +<para> +<!-- .LP --> +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> +<para> +<!-- .LP --> +<function>XAllowDeviceEvents</function> +can generate +<function>BadDevice</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Controlling_Device_Focus"> +<title>Controlling Device Focus</title> +<!-- .XS --> +<!-- (SN Controlling Device Focus --> +<!-- .XE --> +<para> +<!-- .LP --> +The current focus window for an extension input device can be +determined using the +<function>XGetDeviceFocus</function> +function. +Extension devices are focused using the +<function>XSetDeviceFocus</function> +function in the same way that the keyboard is focused using the core +<function>XSetInputFocus</function> +function, except that a device ID is passed as +a function parameter. One additional focus state, +<function>FollowKeyboard ,</function> +is provided for extension devices. +</para> +<para> +<!-- .LP --> +To get the current focus state, revert state, +and focus time of an extension device, use +<function>XGetDeviceFocus .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGetDeviceFocus</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Window<parameter> *focus_return</parameter></paramdef> + <paramdef>int<parameter> *revert_to_return</parameter></paramdef> + <paramdef>Time<parameter> *focus_time_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>focus_return</emphasis> + </term> + <listitem> + <para> +Specifies the address of a variable into which the server can return the ID of +the window that contains the device focus or one of the constants +<function>None ,</function> +<function>PointerRoot ,</function> +or +<function>FollowKeyboard . </function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>revert_to_return</emphasis> + </term> + <listitem> + <para> +Specifies the address of a variable into which the server can +return the current revert_to status for the device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>focus_time_return</emphasis> + </term> + <listitem> + <para> +Specifies the address of a variable into which the server can +return the focus time last set for the device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceFocus</function> +returns the focus state, the revert-to state, +and the last-focus-time for an extension input device. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceFocus</function> +can generate +<function>BadDevice</function> +and +<function>BadMatch</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To set the focus of an extension device, use +<function>XSetDeviceFocus .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSetDeviceFocus</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Window<parameter> focus</parameter></paramdef> + <paramdef>int<parameter> revert_to</parameter></paramdef> + <paramdef>Time<parameter> time</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>focus</emphasis> + </term> + <listitem> + <para> +Specifies the ID of the window to which the device's focus should be set. +This may be a window ID, or +<function>PointerRoot ,</function> +<function>FollowKeyboard ,</function> +or +<function>None .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>revert_to</emphasis> + </term> + <listitem> + <para> +Specifies to which window the focus of the device should revert +if the focus window becomes not viewable. One of the following +constants may be passed: +<function>RevertToParent ,</function> +<function>RevertToPointerRoot ,</function> +<function>RevertToNone ,</function> +or +<function>RevertToFollowKeyboard .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>time</emphasis> + </term> + <listitem> + <para> +Specifies the time. You can pass either a timestamp, expressed in +milliseconds, or +<function>CurrentTime .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetDeviceFocus</function> +changes the focus for an extension input device and the +last-focus-change-time. It 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. +This function causes the X server to generate +<function>DeviceFocusIn</function> +and +<function>DeviceFocusOut</function> +events. +</para> +<para> +<!-- .LP --> +The action taken by the server when this function is requested depends +on the value of the focus argument: +</para> +<itemizedlist> + <listitem> + <para> +If the focus argument is +<function>None ,</function> +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> + <listitem> + <para> +If the focus argument is a window ID, 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> + <listitem> + <para> +If the focus argument is +<function>PointerRoot ,</function> +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> + <listitem> + <para> +If the focus argument is +<function>FollowKeyboard , </function> +the focus window is dynamically taken to be the same as the focus +of the X keyboard at each input event. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The specified focus window must be viewable at the time +<function>XSetDeviceFocus</function> +is called. Otherwise, it generates a +<function>BadMatch</function> +error. +If the focus window later becomes not viewable, +the X server evaluates the revert_to argument +to determine the new focus window. +</para> +<itemizedlist> + <listitem> + <para> +If the revert_to argument is +<function>RevertToParent ,</function> +the focus reverts to the parent (or the closest viewable ancestor), +and the new revert_to value is taken to be +<function>RevertToNone . </function> + </para> + </listitem> + <listitem> + <para> +If the revert_to argument is +<function>RevertToPointerRoot ,</function> +<function>RevertToFollowKeyboard ,</function> +or +<function>RevertToNone ,</function> +the focus reverts to that value. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +When the focus reverts, +the X server generates +<function>DeviceFocusIn</function> +and +<function>DeviceFocusOut</function> +events, but the last-focus-change time is not affected. +</para> +<para> +<!-- .LP --> +<function>XSetDeviceFocus</function> +can generate +<function>BadDevice ,</function> +<function>BadMatch , </function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Controlling_Device_Feedback"> +<title>Controlling Device Feedback</title> +<!-- .XS --> +<!-- (SN Controlling Device Feedback --> +<!-- .XE --> +<para> +<!-- .LP --> +To determine the current feedback settings of an extension input device, use +<function>XGetFeedbackControl .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XFeedbackState * <function> XGetFeedbackControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> *num_feedbacks_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_feedbacks_return</emphasis> + </term> + <listitem> + <para> +Returns the number of feedbacks supported by the device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetFeedbackControl</function> +returns a list of +<function>FeedbackState</function> +structures that describe the feedbacks supported by the specified device. +There is an +<function>XFeedbackState</function> +structure for each class of feedback. These are of +variable length, but the first three members are common to all. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; +} XFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The common members are as follows: +</para> +<itemizedlist> + <listitem> + <para> +The class member identifies the class of feedback. +It may be compared to constants defined in the file +<function>< X11/extensions/XI.h >.</function> +Currently defined feedback constants include: +<function>KbdFeedbackClass , </function> +<function>PtrFeedbackClass ,</function> +<function>StringFeedbackClass ,</function> +<function>IntegerFeedbackClass , </function> +<function>LedFeedbackClass ,</function> +and +<function>BellFeedbackClass .</function> + </para> + </listitem> + <listitem> + <para> +The length member specifies the length of the +<function>FeedbackState</function> +structure and can be used by clients to traverse the list. + </para> + </listitem> + <listitem> + <para> +The id member uniquely identifies a feedback for a given device and class. +This allows a device to support more than one feedback of the same class. +Other feedbacks of other classes or devices may have the same ID. +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Those feedbacks equivalent to those +supported by the core keyboard are reported in class +<function>KbdFeedback</function> +using the +<function>XKbdFeedbackState</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int click; + int percent; + int pitch; + int duration; + int led_mask; + int global_auto_repeat; + char auto_repeats[32]; +} XKbdFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The additional members of the +<function>XKbdFeedbackState</function> +structure report the current state of the feedback: +</para> +<itemizedlist> + <listitem> + <para> +The click member specifies the key-click volume and has a value in the range +0 (off) to 100 (loud). + </para> + </listitem> + <listitem> + <para> +The percent member specifies the bell volume and has a value in the range +0 (off) to 100 (loud). + </para> + </listitem> + <listitem> + <para> +The pitch member specifies the bell pitch in Hz. The range of the value is +implementation-dependent. + </para> + </listitem> + <listitem> + <para> +The duration member specifies the duration in milliseconds of the bell. + </para> + </listitem> + <listitem> + <para> +The led_mask member is a bit mask that describes the current state of up to +32 LEDs. A value of 1 in a bit indicates that the corresponding LED is on. + </para> + </listitem> + <listitem> + <para> +The global_auto_repeat member has a value of +<function>AutoRepeatModeOn</function> +or +<function>AutoRepeatModeOff .</function> + </para> + </listitem> + <listitem> + <para> +The auto_repeats member is a bit vector. Each bit set to 1 indicates +that auto-repeat is enabled for the corresponding key. The vector is +represented as 32 bytes. Byte N (from 0) contains the bits for keys +8N to 8N + 7, with the least significant bit in the byte representing +key 8N. +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Those feedbacks equivalent to those +supported by the core pointer are reported in class +<function>PtrFeedback</function> +using the +<function>XPtrFeedbackState</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int accelNum; + int accelDenom; + int threshold; +} XPtrFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The additional members of the +<function>XPtrFeedbackState</function> +structure report the current state of the feedback: +</para> +<itemizedlist> + <listitem> + <para> +The accelNum member returns the numerator for the acceleration multiplier. + </para> + </listitem> + <listitem> + <para> +The accelDenom member returns the denominator for the acceleration multiplier. + </para> + </listitem> + <listitem> + <para> +The accelDenom member returns the threshold for the acceleration. +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Integer feedbacks are those capable of displaying integer numbers +and reported via the +<function>XIntegerFeedbackState</function> +structure. +The minimum and maximum values that they can display are reported. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int resolution; + int minVal; + int maxVal; +} XIntegerFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The additional members of the +<function>XIntegerFeedbackState</function> +structure report the capabilities of the feedback: +</para> +<itemizedlist> + <listitem> + <para> +The resolution member specifies the number of digits that the feedback +can display. + </para> + </listitem> + <listitem> + <para> +The minVal member specifies the minimum value that the feedback can display. + </para> + </listitem> + <listitem> + <para> +The maxVal specifies the maximum value that the feedback can display. +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +String feedbacks are those that can display character information +and are reported via the +<function>XStringFeedbackState</function> +structure. +Clients set these feedbacks by passing a list of +<function>KeySyms</function> +to be displayed. +The +<function>XGetFeedbackControl</function> +function returns the +set of key symbols that the feedback can display, as well as the +maximum number of symbols that can be displayed. +The +<function>XStringFeedbackState</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int max_symbols; + int num_syms_supported; + KeySym *syms_supported; +} XStringFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The additional members of the +<function>XStringFeedbackState</function> +structure report the capabilities of the feedback: +</para> +<itemizedlist> + <listitem> + <para> +The max_symbols member specifies the maximum number of symbols +that can be displayed. + </para> + </listitem> + <listitem> + <para> +The syms_supported member is a pointer to the list of supported symbols. + </para> + </listitem> + <listitem> + <para> +The num_syms_supported member specifies the length of the list of supported symbols. +<!-- .sp --> + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +Bell feedbacks are those that can generate a sound +and are reported via the +<function>XBellFeedbackState</function> +structure. +Some implementations may support a bell as part of a +<function>KbdFeedback</function> +feedback. Class +<function>BellFeedback</function> +is provided for implementations that do not choose to do +so and for devices that support multiple feedbacks that can produce sound. +The meaning of the members is the same as that of the corresponding fields in +the +<function>XKbdFeedbackState</function> +structure. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int percent; + int pitch; + int duration; +} XBellFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Led feedbacks are those that can generate a light and are reported via the +<function>XLedFeedbackState</function> +structure. +Up to 32 lights per feedback are supported. +Each bit in led_mask +corresponds to one supported light, and the corresponding bit in led_values +indicates whether that light is currently on (1) or off (0). +Some implementations may support leds as part of a +<function>KbdFeedback</function> +feedback. +Class +<function>LedFeedback</function> +is provided for implementations that do not choose to do +so and for devices that support multiple led feedbacks. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + Mask led_values; + Mask led_mask; +} XLedFeedbackState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetFeedbackControl</function> +can generate +<function>BadDevice</function> +and +<function>BadMatch</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To free the information returned by the +<function>XGetFeedbackControl</function> +function, use +<function>XFreeFeedbackList .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void <function> XFreeFeedbackList</function></funcdef> + <paramdef>XFeedbackState<parameter> *list</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies the pointer to the +<function>XFeedbackState</function> +structure returned by +a previous call to +<function>XGetFeedbackControl .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XFreeFeedbackList</function> +frees the list of feedback control information. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To change the settings of a feedback on an extension device, use +<function>XChangeFeedbackControl .</function> +This function modifies the current control values of the specified feedback +using information passed in the appropriate +<function>XFeedbackControl</function> +structure for the feedback. +Which values are modified depends on the valuemask passed. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XChangeFeedbackControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>unsignedlong<parameter> valuemask</parameter></paramdef> + <paramdef>XFeedbackControl<parameter> *value</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuemask</emphasis> + </term> + <listitem> + <para> +Specifies one value for each bit in the mask (least to most significant +bit). The values are associated with the feedbacks for the specified +device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the +<function>XFeedbackControl</function> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XChangeFeedbackControl</function> +controls the device characteristics described by the +<function>XFeedbackControl</function> +structure. +There is an +<function>XFeedbackControl</function> +structure for each class of feedback. +These are of variable length, but the first +three members are common to all and are as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; +} XFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Feedback class +<function>KbdFeedback</function> +controls feedbacks equivalent to those provided by the core keyboard using the +<function>KbdFeedbackControl</function> +structure, which is defined as follows:. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int click; + int percent; + int pitch; + int duration; + int led_mask; + int led_value; + int key; + int auto_repeat_mode; +} XKbdFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +This class controls the device characteristics described by the +<function>XKbdFeedbackControl</function> +structure. These include the key_click_percent, +global_auto_repeat, and individual key auto-repeat. Valid modes +are +<function>AutoRepeatModeOn ,</function> +<function>AutoRepeatModeOff ,</function> +and +<function>AutoRepeatModeDefault .</function> +</para> +<para> +<!-- .LP --> +Valid masks are as follows: +<!-- .sM --> +</para> + +<literallayout class="monospaced"> + +#define DvKeyClickPercent (1><<0) +#define DvPercent (1><<0) +#define DvPitch (1><<0) +#define DvDuration (1><<0) +#define DvLed (1><<0) +#define DvLedMode (1><<0) +#define DvKey (1><<0) +#define DvAutoRepeatMode (1><<0) +</literallayout> + +<para> +<!-- .LP --> +Feedback class +<function>PtrFeedback</function> +controls feedbacks equivalent to those provided by the core pointer using the +<function>PtrFeedbackControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int accelNum; + int accelDenom; + int threshold; +} XPtrFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Which values are modified depends on the valuemask passed. +</para> +<para> +<!-- .LP --> +Valid masks are as follows: +<!-- .sM --> +</para> + +<literallayout class="monospaced"> +#define DvAccelnum (1L<<0) +#define DvAccelDenom (1L<<1) +#define DvThreshold (1L<<2) +</literallayout> + + +<para> +<!-- .LP --> +<!-- .eM --> +The acceleration, expressed as a fraction, is a multiplier for movement. +For example, +specifying 3/1 means that the device moves three times as fast as normal. +The fraction may be rounded arbitrarily by the X server. +Acceleration takes effect only if the device moves more than threshold pixels at +once and applies only to the amount beyond the value in the threshold argument. +Setting a value to -1 restores the default. +The values of the accelNumerator and threshold fields must be nonzero for +the pointer values to be set. +Otherwise, the parameters will be unchanged. +Negative values generate a +<function>BadValue</function> +error, as does a zero value +for the accelDenominator field. +</para> +<para> +<!-- .LP --> +This request fails with a +<function>BadMatch</function> +error if the specified device is not currently reporting relative motion. +If a device that is capable of reporting both relative and absolute motion +has its mode changed from +<function>Relative</function> +to +<function>Absolute</function> +by an +<function>XSetDeviceMode</function> +request, valuator control values +will be ignored by the server while the device is in that mode. +</para> +<para> +<!-- .LP --> +Feedback class +<function>IntegerFeedback</function> +controls integer feedbacks displayed on input devices and are +reported via the +<function>IntegerFeedbackControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int int_to_display; +} XIntegerFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Valid masks are as follows: +<!-- .sM --> +</para> + +<literallayout class="monospaced"> + +#define DvInteger (1L<<0) +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +Feedback class +<function>StringFeedback</function> +controls string feedbacks displayed on input devices +and reported via the +<function>StringFeedbackControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int num_keysyms; + KeySym *syms_to_display; +} XStringFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Valid masks are as follows: +<!-- .sM --> +</para> +<literallayout class="monospaced"> + +#define DvString (1L<<0) +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +Feedback class +<function>BellFeedback</function> +controls a bell on an input device and is reported via the +<function>BellFeedbackControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int percent; + int pitch; + int duration; +} XBellFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Valid masks are as follows: +<!-- .sM --> +</para> + + +<literallayout class="monospaced"> + +#define DvPercent (1L<<1) +#define DvPitch (1L<<2) +#define DvDuration (1L<<3) +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +Feedback class +<function>LedFeedback</function> +controls lights on an input device and are reported via the +<function>LedFeedbackControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID class; + int length; + XID id; + int led_mask; + int led_values; +} XLedFeedbackControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +Valid masks are as follows: +<!-- .sM --> +</para> + +<literallayout class="monospaced"> + +#define DvLed (1L<<4) +#define DvLedMode (1L<<5) +</literallayout> + +<para> +<!-- .LP --> +<!-- .eM --> +<function>XChangeFeedbackControl</function> +can generate +<function>BadDevice ,</function> +<function>BadFeedBack ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Ringing_a_Bell_on_an_Input_Device"> +<title>Ringing a Bell on an Input Device</title> +<!-- .XS --> +<!-- (SN Ringing a Bell on an Input Device --> +<!-- .XE --> +<para> +<!-- .LP --> +To ring a bell on an extension input device, use +<function>XDeviceBell .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XDeviceBell</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>XIDfeedbackclass,<parameter> feedbackid</parameter></paramdef> + <paramdef>int<parameter> percent</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>feedbackclass</emphasis> + </term> + <listitem> + <para> +Specifies the feedbackclass. Valid values are +<function>KbdFeedbackClass</function> +and +<function>BellFeedbackClass .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>feedbackid</emphasis> + </term> + <listitem> + <para> +Specifies the ID of the feedback that has the bell. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>percent</emphasis> + </term> + <listitem> + <para> +Specifies the volume in the range -100 (quiet) to 100 percent (loud). + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XDeviceBell</function> +is analogous to the core +<function>XBell</function> +function. 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 +<function>BadValue</function> +error results. +The volume at which the bell rings when the percent argument is nonnegative is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> + base - [(base * percent) / 100] + percent +</literallayout> +</para> +<para> +<!-- .LP --> +The volume at which the bell rings +when the percent argument is negative is: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> + base + [(base * percent) / 100] +</literallayout> +</para> +<para> +<!-- .LP --> +To change the base volume of the bell, use +<function>XChangeFeedbackControl .</function> +</para> +<para> +<!-- .LP --> +<function>XDeviceBell</function> +can generate +<function>BadDevice</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Controlling_Device_Encoding"> +<title>Controlling Device Encoding</title> +<!-- .XS --> +<!-- (SN Controlling Device Encoding --> +<!-- .XE --> +<para> +<!-- .LP --> +To get the key mapping of an extension device that supports input class +<function>Keys ,</function> +use +<function>XGetDeviceKeyMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>KeySym * <function> XGetDeviceKeyMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>KeyCode<parameter> first_keycode_wanted</parameter></paramdef> + <paramdef>int<parameter> keycode_count</parameter></paramdef> + <paramdef>int<parameter> *keysyms_per_keycode_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>first_keycode_wanted</emphasis> + </term> + <listitem> + <para> +Specifies the first keycode that is to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keycode_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of keycodes that are to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keysyms_per_keycode_return</emphasis> + </term> + <listitem> + <para> +Returns the number of keysyms per keycode. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceKeyMapping </function> +is analogous to the core +<function>XGetKeyboardMapping</function> +function. +It returns the symbols for the specified number of keycodes for the +specified extension device. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceKeyMapping </function> +returns the symbols for the +specified number of keycodes for the +specified extension device, starting with the specified keycode. +The first_keycode_wanted must be greater than or equal to +min-keycode as returned +by the +<function>XListInputDevices</function> +request (else a +<function>BadValue</function> +error results). The following value: +<literallayout class="monospaced"> +first_keycode_wanted + keycode_count - 1 +</literallayout> +</para> +<para> +<!-- .LP --> +must be less than or equal to max-keycode as returned +by the +<function>XListInputDevices</function> +request (else a +<function>BadValue</function> +error results). +</para> +<para> +<!-- .LP --> +The number of elements in the keysyms list is as follows: +<literallayout class="monospaced"> +keycode_count * keysyms_per_keycode_return +</literallayout> +And KEYSYM number N (counting from zero) for keycode K has an index +(counting from zero), in keysyms, of the following: +<literallayout class="monospaced"> +(K - first_keycode_wanted) * keysyms_per_keycode_return + N +</literallayout> +</para> +<para> +<!-- .LP --> +The keysyms_per_keycode_return value is chosen arbitrarily by the server +to be large enough to report all requested symbols. +A special KEYSYM value of +<function>NoSymbol</function> +is used to fill in unused elements for individual keycodes. +</para> +<para> +<!-- .LP --> +To free the data returned by this function, use +<function>XFree .</function> +</para> +<para> +<!-- .LP --> +If the specified device has not first been opened by this client via +<function>XOpenDevice ,</function> +this request will fail with a +<function>BadDevice</function> +error. +If that device does not support input class +<function>Keys ,</function> +this request will fail with a +<function>BadMatch</function> +error. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceKeyMapping </function> +can generate +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To change the keyboard mapping of an extension device that supports input class +<function>Keys ,</function> +use +<function>XChangeDeviceKeyMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XChangeDeviceKeyMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> first_keycode</parameter></paramdef> + <paramdef>int<parameter> keysyms_per_keycode</parameter></paramdef> + <paramdef>KeySym<parameter> *keysyms</parameter></paramdef> + <paramdef>int<parameter> num_codes</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>first_keycode</emphasis> + </term> + <listitem> + <para> +Specifies the first keycode that is to be changed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keysyms_per_keycode</emphasis> + </term> + <listitem> + <para> +Specifies the keysyms that are to be used. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>keysyms</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an array of keysyms. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_codes</emphasis> + </term> + <listitem> + <para> +Specifies the number of keycodes that are to be changed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XChangeDeviceKeyMapping</function> +is analogous to the core +<function>XChangeKeyboardMapping</function> +function. +It defines the symbols for the specified number of keycodes for the +specified extension keyboard device. +</para> +<para> +<!-- .LP --> +If the specified device has not first been opened by this client via +<function>XOpenDevice ,</function> +this request will fail with a +<function>BadDevice</function> +error. +If the specified device does not support input class +<function>Keys ,</function> +this request will fail with a +<function>BadMatch</function> +error. +</para> +<para> +<!-- .LP --> +The number of elements in the keysyms list must be a multiple of +keysyms_per_keycode. Otherwise, +<function>XChangeDeviceKeyMapping</function> +generates a +<function>BadLength</function> +error. +The specified first_keycode must be greater than or equal to +the min_keycode value returned by the +<function>ListInputDevices</function> +request, or this request will fail with a +<function>BadValue</function> +error. In addition, if the following expression is not less than +the max_keycode value returned by the +<function>ListInputDevices</function> +request, the request will fail with a +<function>BadValue</function> +error: +<literallayout class="monospaced"> + first_keycode + (num_codes / keysyms_per_keycode) - 1 +</literallayout> +</para> +<para> +<!-- .LP --> +<function>XChangeDeviceKeyMapping</function> +can generate +<function>BadAlloc ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To obtain the keycodes that are used as modifiers on an +extension device that supports input class +<function>Keys ,</function> +use +<function>XGetDeviceModifierMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XModifierKeymap * <function> XGetDeviceModifierMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceModifierMapping</function> +is analogous to the core +<function>XGetModifierMapping</function> +function. +The +<function>XGetDeviceModifierMapping</function> +function returns a newly created +<function>XModifierKeymap</function> +structure that contains the keys being used as +modifiers for the specified device. +The structure should be freed after use with +<function>XFreeModifierMapping .</function> +If only zero values appear in the set for any modifier, +that modifier is disabled. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceModifierMapping</function> +can generate +<function>BadDevice</function> +and +<function>BadMatch</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To set which keycodes are to be used as modifiers for an extension device, use +<function>XSetDeviceModifierMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSetDeviceModifierMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>XModifierKeymap<parameter> *modmap</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>modmap</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the +<function>XModifierKeymap</function> +structure. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetDeviceModifierMapping</function> +is analogous to the core +<function>XSetModifierMapping</function> +function. +The +<function>XSetDeviceModifierMapping</function> +function specifies the keycodes of the keys, if any, +that are to be used as modifiers. A zero value means +that no key should be used. No two arguments can have the same nonzero +keycode value. Otherwise, +<function>XSetDeviceModifierMapping</function> +generates a +<function>BadValue</function> +error. +There are eight modifiers, and the modifiermap member of the +<function>XModifierKeymap</function> +structure contains eight sets of max_keypermod +keycodes, one for each modifier in the order +<function>Shift ,</function> +<function>Lock ,</function> +<function>Control ,</function> +<function>Mod1 ,</function> +<function>Mod2 ,</function> +<function>Mod3 ,</function> +<function>Mod4 ,</function> +and +<function>Mod5 .</function> +Only nonzero keycodes have meaning in each set, and zero keycodes +are ignored. +In addition, all of the nonzero keycodes must be in the range specified by +min_keycode and max_keycode reported by the +<function>XListInputDevices</function> +function. +Otherwise, +<function>XSetModifierMapping</function> +generates a +<function>BadValue</function> +error. +No keycode may appear twice in the entire map. +Otherwise, it generates a +<function>BadValue</function> +error. +</para> +<para> +<!-- .LP --> +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 +<function>MappingFailed ,</function> +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 +<function>MappingBusy , </function> +and none of the modifiers are changed. +<function>XSetModifierMapping</function> +generates a +<function>DeviceMappingNotify</function> +event on a +<function>MappingSuccess</function> +status. +</para> +<para> +<!-- .LP --> +<function>XSetDeviceModifierMapping</function> +can generate +<function>BadAlloc ,</function> +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Controlling_Button_Mapping"> +<title>Controlling Button Mapping</title> +<!-- .XS --> +<!-- (SN Controlling Button Mapping --> +<!-- .XE --> +<para> +<!-- .LP --> +To set the mapping of the buttons on an extension device, use +<function>XSetDeviceButtonMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSetDeviceButtonMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>unsignedchar<parameter> map[]</parameter></paramdef> + <paramdef>int<parameter> nmap</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>map</emphasis> + </term> + <listitem> + <para> +Specifies the mapping list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nmap</emphasis> + </term> + <listitem> + <para> +Specifies the number of items in the mapping list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetDeviceButtonMapping</function> +sets the mapping of the buttons on an extension device. +If it succeeds, the X server generates a +<function>DeviceMappingNotify</function> +event, and +<function>XSetDeviceButtonMapping</function> +returns +<function>MappingSuccess .</function> +Elements of the list are indexed starting from one. +The length of the list must be the same as +<function>XGetDeviceButtonMapping</function> +would return, or a +<function>BadValue</function> +error results. +The index is a button number, and the element of the list +defines the effective number. +A zero element disables a button, and elements are not restricted in +value by the number of physical buttons. +However, no two elements can have the same nonzero value, or a +<function>BadValue</function> +error results. +If any of the buttons to be altered are logically in the down state, +<function>XSetDeviceButtonMapping</function> +returns +<function>MappingBusy ,</function> +and the mapping is not changed. +</para> +<para> +<!-- .LP --> +<function>XSetDeviceButtonMapping</function> +can generate +<function>BadDevice ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To get the button mapping, use +<function>XGetDeviceButtonMapping .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGetDeviceButtonMapping</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>unsignedchar<parameter> map_return[]</parameter></paramdef> + <paramdef>int<parameter> nmap</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>map_return</emphasis> + </term> + <listitem> + <para> +Specifies the mapping list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nmap</emphasis> + </term> + <listitem> + <para> +Specifies the number of items in the mapping list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceButtonMapping</function> +returns the current mapping of the specified extension device. +Elements of the list are indexed starting from one. +<function>XGetDeviceButtonMapping</function> +returns the number of physical buttons actually on the pointer. +The nominal mapping for the buttons is the identity mapping: map[i]=i. +The nmap argument specifies the length of the array where the button +mapping is returned, and only the first nmap elements are returned +in map_return. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceButtonMapping</function> +can generate +<function>BadDevice</function> +and +<function>BadMatch</function> +errors. +</para> +</sect3> +<sect3 id="Obtaining_the_State_of_a_Device"> +<title>Obtaining the State of a Device</title> +<!-- .XS --> +<!-- (SN Obtaining the State of a Device --> +<!-- .XE --> +<para> +<!-- .LP --> +To obtain information that describes the state of the keys, buttons, and +valuators of an extension device, use +<function>XQueryDeviceState .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XDeviceState * <function> XQueryDeviceState</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XQueryDeviceState</function> +returns a pointer to an +<function>XDeviceState</function> +structure, which points to a list of +structures that describe the state of the keys, buttons, and valuators +on the device: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID device_id; + int num_classes; + XInputClass *data; +} XDeviceState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The structures are of variable length, but the first +two members are common to all and are as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + unsigned char class; + unsigned char length; +} XInputClass; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The class member contains a class identifier. This identifier can be +compared with constants defined in the file +<function>< X11/extensions/XI.h >.</function> +Currently defined constants are: +<function>KeyClass ,</function> +<function>ButtonClass ,</function> +and +<function>ValuatorClass .</function> +</para> +<para> +<!-- .LP --> +The length member contains the length of the structure and can be used +by clients to traverse the list. +</para> +<para> +<!-- .LP --> +The +<function>XValuatorState</function> +structure describes the current state of the valuators +on the device. +The num_valuators member contains the number of valuators +on the device. +The mode member is a mask whose bits report the data mode +and other state information for the device. +The following bits are currently defined: +<literallayout class="monospaced"> +<!-- .TA .5i 1.5i 2.5i --> +<!-- .ta .5i 1.5i 2.5i --> + DeviceMode 1 << 0 Relative = 0, Absolute = 1 + ProximityState 1 << 1 InProximity = 0, OutOfProximity = 1 +</literallayout> +The valuators member contains a pointer to an array of integers that +describe the current value of the valuators. +If the mode is +<function>Relative ,</function> +these values are undefined. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + unsigned char class; + unsigned char length; + unsigned char num_valuators; + unsigned char mode; + int *valuators; +} XValuatorState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XKeyState</function> +structure describes the current state of the keys +on the device. Byte N (from 0) contains the +bits for key 8N to 8N + 7 with the least significant bit in the +byte representing key 8N. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + unsigned char class; + unsigned char length; + short num_keys; + char keys[32]; +} XKeyState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XButtonState</function> +structure describes the current state of the buttons +on the device. Byte N (from 0) contains the bits for button 8N to 8N + 7 +with the least significant bit in the +byte representing button 8N. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + unsigned char class; + unsigned char length; + short num_buttons; + char buttons[32]; +} XButtonState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XQueryDeviceState</function> +can generate +<function>BadDevice</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To free the data returned by this function, use +<function>XFreeDeviceState .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void <function> XFreeDeviceState</function></funcdef> + <paramdef>XDeviceState<parameter> *state</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>state</emphasis> + </term> + <listitem> + <para> +Specifies the pointer to the +<function>XDeviceState</function> +data returned by a previous call to +<function>XQueryDeviceState .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XFreeDeviceState</function> +frees the device state data. +</para> +</sect3> +</sect2> +<sect2 id="Events"> +<title>Events</title> +<!-- .XS --> +<!-- (SN Events --> +<!-- .XE --> +<para> +<!-- .LP --> +The input extension creates input events analogous to the core input events. +These extension input events are generated by manipulating one of the +extension input devices. +The remainder of this section discusses the following X Input Extension +event topics: +</para> +<itemizedlist> + <listitem> + <para> +Event types + </para> + </listitem> + <listitem> + <para> +Event classes + </para> + </listitem> + <listitem> + <para> +Event structures + </para> + </listitem> +</itemizedlist> +<sect3 id="Event_Types"> +<title>Event Types</title> +<!-- .XS --> +<!-- (SN Event Types --> +<!-- .XE --> +<para> +<!-- .LP --> +Event types are integer numbers that a client can use to determine what +kind of event it has received. The client compares the type field of +the event structure with known event types to make this determination. +</para> +<para> +<!-- .LP --> +The core input event types are constants and are defined in the header file +<function>< X11/X.h >.</function> +Extension event types are not constants. Instead, they +are dynamically allocated by the extension's request to the X server +when the extension is initialized. Because of this, extension event +types must be obtained by the client from the server. +</para> +<para> +<!-- .LP --> +The client program determines the event type for an extension event by using +the information returned by the +<function>XOpenDevice</function> +request. +This type can then be used for comparison with the type field +of events received by the client. +</para> +<para> +<!-- .LP --> +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> +<!-- .LP --> +The following table lists the event category and its associated event +type or types. +</para> + +<informaltable> + <tgroup cols='2' align='center'> + <colspec colname='c1'/> + <colspec colname='c2'/> + <thead> + <row> + <entry>Event Category</entry> + <entry>Event Type</entry> + </row> + </thead> + <tbody> + <row> + <entry>Device key</entry> + <entry><function>DeviceKeyPress</function></entry> + </row> + <row> + <entry></entry> + <entry><function>DeviceKeyRelease</function></entry> + </row> + <row> + <entry>Device motion</entry> + <entry><function>DeviceButtonPress</function></entry> + </row> + <row> + <entry></entry> + <entry><function>DeviceButtonRelease</function></entry> + </row> + <row> + <entry></entry> + <entry><function>DeviceMotionNotify</function></entry> + </row> + <row> + <entry>Device input focus</entry> + <entry><function>DeviceFocusIn</function></entry> + </row> + <row> + <entry></entry> + <entry><function>DeviceFocusOut</function></entry> + </row> + <row> + <entry>Device state notification</entry> + <entry><function>DeviceStateNotify</function></entry> + </row> + <row> + <entry>Device proximity</entry> + <entry><function>ProximityIn</function></entry> + </row> + <row> + <entry></entry> + <entry><function>ProximityOut</function></entry> + </row> + <row> + <entry>Device mapping</entry> + <entry><function>DeviceMappingNotify</function></entry> + </row> + <row> + <entry>Device change</entry> + <entry><function>ChangeDeviceNotify</function></entry> + </row> + </tbody> + </tgroup> +</informaltable> + +</sect3> +<sect3 id="Event_Classes"> +<title>Event Classes</title> +<!-- .XS --> +<!-- (SN Event Classes --> +<!-- .XE --> +<para> +<!-- .LP --> +Event classes are integer numbers that are used in the same way as the +core event masks. They are used by a client program to indicate to the +server which events that client program wishes to receive. +</para> +<para> +<!-- .LP --> +The core input event masks are constants and are defined in the header file +<function>< X11/X.h >.</function> +Extension event classes are not constants. Instead, they are dynamically +allocated by the extension's request to the X server +when the extension is initialized. Because of this, extension event +classes must be obtained by the client from the server. +</para> +<para> +<!-- .LP --> +The event class for an extension event and device is obtained from +information returned by the +<function>XOpenDevice</function> +function. +This class can then be used in an +<function>XSelectExtensionEvent</function> +request to ask that events of that type from that device be sent to +the client program. +</para> +<para> +<!-- .LP --> +For +<function>DeviceButtonPress</function> +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 +<function>DeviceButtonRelease</function> +event for each +<function>DeviceButtonPress</function> +event it receives, it should specify the +<function>DeviceButtonPressGrab</function> +class in addition to the +<function>DeviceButtonPress</function> +class. +This restricts the client in that only one client at a time +may request +<function>DeviceButtonPress</function> +events from the same device and +window if any client specifies this class. +</para> +<para> +<!-- .LP --> +If any client has specified the +<function>DeviceButtonPressGrab</function> +class, any requests by any other client that specify the same device +and window and specify either +<function>DeviceButtonPress</function> +or +<function>DeviceButtonPressGrab</function> +will cause an +<function>Access</function> +error to be generated. +</para> +<para> +<!-- .LP --> +If only the +<function>DeviceButtonPress</function> +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> +<!-- .LP --> +The client may also select +<function>DeviceMotion</function> +events only when a button is down. +It does this by specifying the event classes +<function>DeviceButton1Motion</function> +through +<function>DeviceButton5Motion . </function> +An input device will support only +as many button motion classes as it has buttons. +</para> +</sect3> +<sect3 id="Event_Structures"> +<title>Event Structures</title> +<!-- .XS --> +<!-- (SN Event Structures --> +<!-- .XE --> +<para> +<!-- .LP --> +Each extension event type has a corresponding structure declared in +<function>< X11/extensions/XInput.h >.</function> +All event structures have the following common members: +<variablelist> + <varlistentry> + <term> + type + </term> + <listitem> + <para> +Set to the event type number that uniquely identifies it. For example, +when the X server reports a +<function>DeviceKeyPress</function> +event to a client application, it sends an +<function>XDeviceKeyPressEvent</function> +structure. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + serial + </term> + <listitem> + <para> +Set from the serial number reported in the protocol but expanded from the +16-bit least significant bits to a full 32-bit value. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + send_event + </term> + <listitem> + <para> +Set to +<function>True</function> +if the event came from an +<function>XSendEvent</function> +request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + display + </term> + <listitem> + <para> +Set to a pointer to a structure that defines the display +on which the event was read. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +Extension event structures report the current position of the X pointer. +In addition, if the device reports motion data and is reporting absolute data, +the current value of any valuators the device contains is also reported. +</para> +<sect4 id="Device_Key_Events"> +<title>Device Key Events</title> +<!-- .XS --> +<!-- (SN Device Key Events --> +<!-- .XE --> +<para> +<!-- .LP --> +Key events from extension devices contain all the information that is +contained in a key event from the X keyboard. In addition, they contain +a device ID and report the current value of any valuators on the device, +if that device is reporting absolute data. +If data for more than six valuators is being reported, more than one +key event will be sent. +The axes_count member contains the number of axes that are being +reported. The server sends as many of these events as are +needed to report the device data. Each event contains the total number +of axes reported in the axes_count member and the first axis reported +in the current event in the first_axis member. +If the device supports input class +<function>Valuators , </function> +but is not reporting absolute mode data, +the axes_count member contains zero (0). +</para> +<para> +<!-- .LP --> +The location reported in +the x, y and x_root, y_root members is the location of the core X pointer. +</para> +<para> +<!-- .LP --> +The +<function>XDeviceKeyEvent</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed */ + Bool send_event; /* true if from SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int keycode; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; +} XDeviceKeyEvent; + +typedef XDeviceKeyEvent XDeviceKeyPressedEvent; +typedef XDeviceKeyEvent XDeviceKeyReleasedEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Device_Button_Events"> +<title>Device Button Events</title> +<!-- .XS --> +<!-- (SN Device Button Events --> +<!-- .XE --> +<para> +<!-- .LP --> +Button events from extension devices contain all the information that is +contained in a button event from the X pointer. In addition, they contain +a device ID and report the current value of any valuators on the device +if that device is reporting absolute data. +If data for more than six valuators is being reported, more than one +button event may be sent. +The axes_count member contains the number of axes that are being +reported. The server sends as many of these events as are +needed to report the device data. Each event contains the total number +of axes reported in the axes_count member and the first axis reported +in the current event in the first_axis member. +If the device supports input class +<function>Valuators , </function> +but is not reporting absolute mode data, +the axes_count member contains zero (0). +</para> +<para> +<!-- .LP --> +The location reported in +the x, y and x_root, y_root members is the location of the core X pointer. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int button; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; +} XDeviceButtonEvent; + +typedef XDeviceButtonEvent XDeviceButtonPressedEvent; +typedef XDeviceButtonEvent XDeviceButtonReleasedEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Device_Motion_Events"> +<title>Device Motion Events</title> +<!-- .XS --> +<!-- (SN Device Motion Events --> +<!-- .XE --> +<para> +<!-- .LP --> +Motion events from extension devices contain all the information that is +contained in a motion event from the X pointer. In addition, they contain +a device ID and report the current value of any valuators on the device. +</para> +<para> +<!-- .LP --> +The location reported in +the x, y and x_root, y_root members is the location of the core X pointer, +and so is 2-dimensional. +</para> +<para> +<!-- .LP --> +Extension motion devices may report motion data for a variable number of +axes. +The axes_count member contains the number of axes that are being +reported. The server sends as many of these events as are +needed to report the device data. Each event contains the total number +of axes reported in the axes_count member and the first axis reported +in the current event in the first_axis member. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window that the event occurred on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + char is_hint; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; +} XDeviceMotionEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Device_Focus_Events"> +<title>Device Focus Events</title> +<!-- .XS --> +<!-- (SN Device Focus Events --> +<!-- .XE --> +<para> +<!-- .LP --> +These events are equivalent to the core focus events. +They contain the same information, with the addition +of a device ID to identify which device has had a focus change, +and a timestamp. +</para> +<para> +<!-- .LP --> +<function>DeviceFocusIn</function> +and +<function>DeviceFocusOut</function> +events are generated for +focus changes of extension devices in the same manner as core focus +events are generated. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 2.5i --> +<!-- .ta .5i 2.5i --> +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window it is reported relative to */ + XID deviceid; + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonLinear,NotifyNonLinearVirtual, NotifyPointer, + * NotifyPointerRoot, NotifyDetailNone + */ + Time time; +} XDeviceFocusChangeEvent; + +typedef XDeviceFocusChangeEvent XDeviceFocusInEvent; +typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Device_StateNotify_Event"> +<title>Device StateNotify Event</title> +<!-- .XS --> +<!-- (SN Device StateNotify Event --> +<!-- .XE --> +<para> +<!-- .LP --> +This event is analogous to the core keymap event but +reports the current state of the device for each +input class that it supports. +It is generated after every +<function>DeviceFocusIn</function> +event and +<function>EnterNotify</function> +event and is delivered to clients who have selected +<function>XDeviceStateNotify</function> +events. +</para> +<para> +<!-- .LP --> +If the device supports input class +<function>Valuators ,</function> +the mode member in the +<function>XValuatorStatus</function> +structure is a bitmask that reports the device mode, +proximity state, and other state information. +The following bits are currently defined: +<literallayout class="monospaced"> +<!-- .TA .5i 1.5i --> +<!-- .ta .5i 1.5i --> + 0x01 Relative = 0, Absolute = 1 + 0x02 InProximity = 0, OutOfProximity = 1 +</literallayout> +</para> +<para> +<!-- .LP --> +If the device supports more valuators than can be reported in a single +<function>XEvent ,</function> +multiple +<function>XDeviceStateNotify</function> +events will be generated. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + unsigned char class; + unsigned char length; +} XInputClass; + +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + XID deviceid; + Time time; + int num_classes; + char data[64]; +} XDeviceStateNotifyEvent; + +typedef struct { + unsigned char class; + unsigned char length; + unsigned char num_valuators; + unsigned char mode; + int valuators[6]; +} XValuatorStatus; + +typedef struct { + unsigned char class; + unsigned char length; + short num_keys; + char keys[32]; +} XKeyStatus; + +typedef struct { + unsigned char class; + unsigned char length; + short num_buttons; + char buttons[32]; +} XButtonStatus; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Device_Mapping_Event"> +<title>Device Mapping Event</title> +<!-- .XS --> +<!-- (SN Device Mapping Event --> +<!-- .XE --> +<para> +<!-- .LP --> +This event is equivalent to the core +<function>MappingNotify</function> +event. +It notifies client programs when the mapping of keys, +modifiers, or buttons on an extension device has changed. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; + unsigned long serial; + Bool send_event; + Display *display; + Window window; + XID deviceid; + Time time; + int request; + int first_keycode; + int count; +} XDeviceMappingEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="ChangeDeviceNotify_Event"> +<title>ChangeDeviceNotify Event</title> +<!-- .XS --> +<!-- (SN ChangeDeviceNotify Event --> +<!-- .XE --> +<para> +<!-- .LP --> +This event has no equivalent in the core protocol. It notifies client +programs when one of the core devices has been changed. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; + unsigned long serial; + Bool send_event; + Display *display; + Window window; + XID deviceid; + Time time; + int request; +} XChangeDeviceNotifyEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +<sect4 id="Proximity_Events"> +<title>Proximity Events</title> +<!-- .XS --> +<!-- (SN Proximity Events --> +<!-- .XE --> +<para> +<!-- .LP --> +These events have no equivalent in the core protocol. Some input +devices such as graphics tablets or touchscreens may send these +events to indicate that a stylus has moved into or out of contact +with a positional sensing surface. +</para> +<para> +<!-- .LP --> +The event contains the current value of any valuators on the device +if that device is reporting absolute data. +If data for more than six valuators is being reported, more than one +proximity event may be sent. +The axes_count member contains the number of axes that are being +reported. The server sends as many of these events as are +needed to report the device data. Each event contains the total number +of axes reported in the axes_count member and the first axis reported +in the current event in the first_axis member. +If the device supports input class +<function>Valuators , </function> +but is not reporting absolute mode data, +the axes_count member contains zero (0). +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i 3i --> +<!-- .ta .5i 3i --> +typedef struct { + int type; /* ProximityIn or ProximityOut */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + XID deviceid; + Window root; + Window subwindow; + Time time; + int x, y; + int x_root, y_root; + unsigned int state; + Bool same_screen; + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; +} XProximityNotifyEvent; + +typedef XProximityNotifyEvent XProximityInEvent; +typedef XProximityNotifyEvent XProximityOutEvent; +</literallayout> +<!-- .eM --> +</para> +</sect4> +</sect3> +</sect2> +<sect2 id="Event_Handling_Functions"> +<title>Event Handling Functions</title> +<!-- .XS --> +<!-- (SN Event Handling Functions --> +<!-- .XE --> +<para> +<!-- .LP --> +This section discusses the X Input Extension +event handling functions that allow you to: +</para> +<itemizedlist> + <listitem> + <para> +Determine the extension version + </para> + </listitem> + <listitem> + <para> +List the available devices + </para> + </listitem> + <listitem> + <para> +Enable and disable extension devices + </para> + </listitem> + <listitem> + <para> +Change the mode of a device + </para> + </listitem> + <listitem> + <para> +Initialize valuators on an input device + </para> + </listitem> + <listitem> + <para> +Get input device controls + </para> + </listitem> + <listitem> + <para> +Change input device controls + </para> + </listitem> + <listitem> + <para> +Select extension device events + </para> + </listitem> + <listitem> + <para> +Determine selected device events + </para> + </listitem> + <listitem> + <para> +Control event propogation + </para> + </listitem> + <listitem> + <para> +Send an event + </para> + </listitem> + <listitem> + <para> +Get motion history + </para> + </listitem> +</itemizedlist> +<sect3 id="Determining_the_Extension_Version"> +<title>Determining the Extension Version</title> +<!-- .XS --> +<!-- (SN Determining the Extension Version --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XExtensionVersion * <function> XGetExtensionVersion</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>char<parameter> *name</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>name</emphasis> + </term> + <listitem> + <para> +Specifies the name of the desired extension. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetExtensionVersion</function> +allows a client to determine whether a server supports +the desired version of the input extension. +</para> +<para> +<!-- .LP --> +The +<function>XExtensionVersion</function> +structure returns information about the version of the extension +supported by the server and is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + Bool present; + short major_version; + short minor_version; +} XExtensionVersion; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The major and minor versions can be compared with constants defined in +the header file +<function>< X11/extensions/XI.h >.</function> +Each version is a superset of the previous versions. +</para> +<para> +<!-- .LP --> +You should use +<function>XFree</function> +to free the data returned by this function. +</para> +</sect3> +<sect3 id="Listing_Available_Devices"> +<title>Listing Available Devices</title> +<!-- .XS --> +<!-- (SN Listing Available Devices --> +<!-- .XE --> +<para> +<!-- .LP --> +A client program that wishes to access a specific device +must first determine whether that device is connected to the X server. This +is done through the +<function>XListInputDevices</function> +function, which will return a list of all devices that can be opened +by the X server. The client program can use one +of the names defined in the +<function>< X11/extensions/XI.h ></function> +header file in an +<function>XInternAtom </function> +request to determine the device type of the desired device. This type +can then be compared with the device types returned by the +<function>XListInputDevices</function> +request. +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XDeviceInfo * <function> XListInputDevices</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>int<parameter> *ndevices</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>ndevices</emphasis> + </term> + <listitem> + <para> +Specifies the address of a variable into which the server +can return the number of input devices available to the X server. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XListInputDevices</function> +allows a client to determine which devices +are available for X input and information about those devices. +An array of +<function>XDeviceInfo</function> +structures is returned, with one element in the array for each device. +The number of devices is returned in the ndevices argument. +</para> +<para> +<!-- .LP --> +The X pointer device and X keyboard device are reported, as well as +all available extension input devices. The use member of the +<function>XDeviceInfo</function> +structure specifies the current use of the device. +If the value of this member is +<function>IsXPointer ,</function> +the device is the X pointer device. If the value is +<function>IsXKeyboard ,</function> +the device is the X keyboard device. If the value is +<function>IsXExtensionDevice ,</function> +the device is available for use as an extension input device. +</para> +<para> +<!-- .LP --> +Each +<function>XDeviceInfo</function> +entry contains a pointer to a list of structures +that describe the characteristics of each class +of input supported by that device. The num_classes member +contains the number of entries in that list. +</para> +<para> +<!-- .LP --> +If the device supports input class +<function>Valuators ,</function> +one of the structures pointed to by the +<function>XDeviceInfo</function> +structure will be an +<function>XValuatorInfo</function> +structure. The axes member of that structure +contains the address of an array of +<function>XAxisInfo</function> +structures. +There is one element in this array for each axis of motion +reported by the device. The number of elements in this +array is contained in the num_axes element of the +<function>XValuatorInfo</function> +structure. +The size of the motion buffer for the device is +reported in the motion_buffer member of the +<function>XValuatorInfo</function> +structure. +</para> +<para> +<!-- .LP --> +The +<function>XDeviceInfo</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct _XDeviceInfo { + XID id; + Atom type; + char *name; + int num_classes; + int use; + XAnyClassPtr inputclassinfo; +} XDeviceInfo; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The structures pointed to by the +<function>XDeviceInfo</function> +structure are defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct _XKeyInfo { + XID class; + int length; + unsigned short min_keycode; + unsigned short max_keycode; + unsigned short num_keys; +} XKeyInfo; + +typedef struct _XButtonInfo { + XID class; + int length; + short num_buttons; +} XButtonInfo; + +typedef struct _XValuatorInfo { + XID class; + int length; + unsigned char num_axes; + unsigned char mode; + unsigned long motion_buffer; + XAxisInfoPtr axes; +} XValuatorInfo; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XAxisInfo</function> +structure pointed to by the +<function>XValuatorInfo</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct _XAxisInfo { + int resolution; + int min_value; + int max_value; +} XAxisInfo; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The following atom names are defined in the +<function>< X11/extensions/XI.h ></function> +header file. +<literallayout class="monospaced"> +<!-- .TA 2i --> +<!-- .ta 2i --> +MOUSE QUADRATURE +TABLET SPACEBALL +KEYBOARD DATAGLOVE +TOUCHSCREEN EYETRACKER +TOUCHPAD CURSORKEYS +BUTTONBOX FOOTMOUSE +BARCODE ID_MODULE +KNOB_BOX ONE_KNOB +TRACKBALL NINE_KNOB\s+1 +</literallayout> +</para> +<para> +<!-- .LP --> +These names can be used in an +<function>XInternAtom</function> +request to return an atom that can be used for comparison +with the type member of the +<function>XDeviceInfo</function> +structure. +</para> +<para> +<!-- .LP --> +<function>XListInputDevices</function> +returns NULL if there are no input devices to list. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To free the data returned by +<function>XListInputDevices ,</function> +use +<function>XFreeDeviceList .</function> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void <function> XFreeDeviceList</function></funcdef> + <paramdef>XDeviceInfo<parameter> *list</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>list</emphasis> + </term> + <listitem> + <para> +Specifies the pointer to the +<function>XDeviceInfo</function> +array returned by a previous call to +<function>XListInputDevices .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XFreeDeviceList</function> +frees the list of input device information. +</para> +</sect3> +<sect3 id="Enabling_and_Disabling_Extension_Devices"> +<title>Enabling and Disabling Extension Devices</title> +<!-- .XS --> +<!-- (SN Enabling and Disabling Extension Devices --> +<!-- .XE --> +<para> +<!-- .LP --> +Each client program that wishes to access an extension device must request +that the server open that device by calling the +<function>XOpenDevice</function> +function. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XDevice * <function> XOpenDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XID<parameter> device_id</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device_id</emphasis> + </term> + <listitem> + <para> +Specifies the ID that uniquely identifies the device to be opened. +This ID is obtained from the +<function>XListInputDevices</function> +request. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XOpenDevice</function> +opens the device for the requesting client and, on success, returns an +<function>XDevice</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID device_id; + int num_classes; + XInputClassInfo *classes; +} XDevice; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The +<function>XDevice</function> +structure contains a pointer to an array of +<function>XInputClassInfo</function> +structures. Each element in that array +contains information about events of a particular input class supported +by the input device. +</para> +<para> +<!-- .LP --> +The +<function>XInputClassInfo</function> +structure is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + unsigned char input_class; + unsigned char event_type_base; +} XInputClassInfo; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +A client program can determine the event +type and event class for a given event by using macros defined by the +input extension. The name of the macro corresponds to the desired event, +and the macro is passed the structure that describes the device from which +input is desired, for example: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> + DeviceKeyPress(XDevice *device, event_type, event_class) +</literallayout> +</para> +<para> +<!-- .LP --> +The macro will fill in the values of the event class to be used in an +<function>XSelectExtensionEvent</function> +request to select the event and the event type to be used in comparing +with the event types of events received via +<function>XNextEvent .</function> +</para> +<para> +<!-- .LP --> +<function>XOpenDevice</function> +can generate +<function>BadDevice</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +Before terminating, the client program should request that the server close +the device by calling the +<function>XCloseDevice</function> +function. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XCloseDevice</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device to be closed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XCloseDevice</function> +closes the device for the requesting client and frees the associated +<function>XDevice</function> +structure. +</para> +<para> +<!-- .LP --> +A client may open the same extension device more than once. Requests +after the first successful one return an additional +<function>XDevice</function> +structure +with the same information as the first, but otherwise have no effect. +A single +<function>XCloseDevice</function> +request will terminate that client's access to the device. +</para> +<para> +<!-- .LP --> +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, any queued events are released. +</para> +<para> +<!-- .LP --> +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> +<!-- .LP --> +<function>XCloseDevice</function> +can generate +<function>BadDevice</function> +errors. +</para> +</sect3> +<sect3 id="Changing_the_Mode_of_a_Device"> +<title>Changing the Mode of a Device</title> +<!-- .XS --> +<!-- (SN Changing the Mode of a Device --> +<!-- .XE --> +<para> +<!-- .LP --> +Some devices are capable of reporting either relative or absolute motion +data. +To change the mode of a device from relative to absolute, use +<function>XSetDeviceMode .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSetDeviceMode</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose mode should be changed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the mode. You can pass +<function>Absolute</function> +or +<function>Relative .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetDeviceMode</function> +allows a client to request the server to change the mode of a +device that is capable of reporting either absolute positional data or relative +motion data. If the device is invalid or if the client has not previously +requested that the server open the device via an +<function>XOpenDevice</function> +request, this request will fail with a +<function>BadDevice</function> +error. +If the device does not support input class +<function>Valuators</function> +or if it is not capable of reporting the specified mode, +the request will fail with a +<function>BadMatch</function> +error. +</para> +<para> +<!-- .LP --> +This request will fail and return +<function>DeviceBusy</function> +if another client has already opened the device and requested a different mode. +</para> +<para> +<!-- .LP --> +<function>XSetDeviceMode</function> +can generate +<function>BadDevice ,</function> +<function>BadMatch ,</function> +<function>BadMode ,</function> +and +<function>DeviceBusy</function> +errors. +</para> +</sect3> +<sect3 id="Initializing_Valuators_on_an_Input_Device"> +<title>Initializing Valuators on an Input Device</title> +<!-- .XS --> +<!-- (SN Initializing Valuators on an Input Device --> +<!-- .XE --> +<para> +<!-- .LP --> +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 +<function>Absolute .</function> +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To initialize the valuators on such a device, use +<function>XSetDeviceValuators .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Status <function> XSetDeviceValuators</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int*valuators,first_valuator,<parameter> num_valuators</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose valuators should be initialized. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>valuators</emphasis> + </term> + <listitem> + <para> +Specifies the values to which each valuator should be set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>first_valuator</emphasis> + </term> + <listitem> + <para> +Specifies the first valuator to be set. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>num_valuators</emphasis> + </term> + <listitem> + <para> +Specifies the number of valuators to be set. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSetDeviceValuators</function> +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. +A +<function>BadValue</function> +error results if the number of valuators supported by the device +is less than the following expression: +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> + first_valuator + num_valuators +</literallayout> +</para> +<para> +<!-- .LP --> +If the request succeeds, +<function>Success</function> +is returned. If the specified device is grabbed by some other client, +the request will fail and a status of +<function>AlreadyGrabbed</function> +will be returned. +</para> +<para> +<!-- .LP --> +<function>XSetDeviceValuators</function> +can generate +<function>BadDevice ,</function> +<function>BadLength ,</function> +<function>BadMatch ,</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Getting_Input_Device_Controls"> +<title>Getting Input Device Controls</title> +<!-- .XS --> +<!-- (SN Getting Input Device Controls --> +<!-- .XE --> +<para> +<!-- .LP --> +Some input devices support various configuration controls +that can be queried or changed by clients. The set of supported +controls will vary from one input device to another. Requests +to manipulate these controls will fail if either the target +X server or the target input device does not support the +requested device control. +</para> +<para> +<!-- .LP --> +Each device control has a unique identifier. Information +passed with each device control varies in length and is mapped +by data structures unique to that device control. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To query a device control, use +<function>XGetDeviceControl .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XDeviceControl * <function> XGetDeviceControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> control</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose configuration control status is to be returned. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>control</emphasis> + </term> + <listitem> + <para> +Identifies the specific device control to be queried. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceControl</function> +returns the current state of the specified device control. +If the target X server does not support that device control, a +<function>BadValue</function> +error is returned. +If the specified device does not support that device control, a +<function>BadMatch</function> +error +is returned. +</para> +<para> +<!-- .LP --> +If the request is successful, a pointer to a generic +<function>XDeviceState</function> +structure is returned. The information returned varies according +to the specified control and is mapped by a structure appropriate +for that control. +The first two members are common to all device controls +and are defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID control; + int length; +} XDeviceState; +\fP +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The control may be compared to constants defined in the file +<function>< X11/extensions/XI.h >.</function> +Currently defined device controls include DEVICE_RESOLUTION. +</para> +<para> +<!-- .LP --> +The information returned for the DEVICE_RESOLUTION control is +defined in the +<function>XDeviceResolutionState</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID control; + int length; + int num_valuators; + int *resolutions; + int *min_resolutions; + int *max_resolutions; +} XDeviceResolutionState; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +This device control returns a list of valuators and the range of +valid resolutions allowed for each. Valuators are numbered +beginning with zero (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> +<!-- .LP --> +When this control is specified, +<function>XGetDeviceControl</function> +fails with a +<function>BadMatch</function> +error if the specified device has no valuators. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceControl</function> +can generate +<function>BadMatch</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Changing_Input_Device_Controls"> +<title>Changing Input Device Controls</title> +<!-- .XS --> +<!-- (SN Changing Input Device Controls --> +<!-- .XE --> +<para> +<!-- .LP --> +Some input devices support various configuration controls +that can be changed by clients. Typically, this would be +done to initialize the device to a known state or configuration. +The set of supported controls will vary from one input device +to another. Requests to manipulate these controls will fail if +either the target X server or the target input device does not +support the requested device control. Setting the device control +will also fail if the target input device is grabbed by another +client or is open by another client and has been set to a conflicting +state. +</para> +<para> +<!-- .LP --> +Each device control has a unique identifier. Information +passed with each device control varies in length and is mapped +by data structures unique to that device control. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To change a device control, use +<function>XChangeDeviceControl .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>Status <function> XChangeDeviceControl</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>int<parameter> control</parameter></paramdef> + <paramdef>XDeviceControl<parameter> *value</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose configuration control status is to be modified. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>control</emphasis> + </term> + <listitem> + <para> +Identifies the specific device control to be changed. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>value</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an +<function>XDeviceControl</function> +structure that describes which control is to be changed +and how it is to be changed. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XChangeDeviceControl</function> +changes the current state of the specified device control. +If the target X server does not support that device control, a +<function>BadValue</function> +error is returned. +If the specified device does not support that device control, a +<function>BadMatch</function> +error is returned. +If another client has the target device grabbed, a status of +<function>AlreadyGrabbed</function> +is returned. +If another client has the device open and has set it to a +conflicting state, a status of +<function>DeviceBusy</function> +is returned. +If the request fails for any reason, the device control will not +be changed. +</para> +<para> +<!-- .LP --> +If the request is successful, the device control will be changed +and a status of +<function>Success</function> +is returned. +The information passed varies according to the specified control +and is mapped by a structure appropriate for that control. +The first two members are common to all device controls: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID control; + int length; +} XDeviceControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The control may be set using constants defined in the +<function>< X11/extensions/XI.h ></function> +header file. +Currently defined device controls include DEVICE_RESOLUTION. +</para> +<para> +<!-- .LP --> +The information that can be changed by the DEVICE_RESOLUTION +control is defined in the +<function>XDeviceResolutionControl</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + XID control; + int length; + int first_valuator; + int num_valuators; + int *resolutions; +} XDeviceResolutionControl; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +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. The num_valuators member +specifies the number of valuators in the resolutions list. +</para> +<para> +<!-- .LP --> +When this control is specified, +<function>XChangeDeviceControl</function> +fails with a +<function>BadMatch</function> +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 +<function>XGetDeviceControl ),</function> +<function>XChangeDeviceControl</function> +fails with a +<function>BadValue</function> +error. +A +<function>BadValue</function> +error results if the number of valuators supported by the device +is less than the following expression: +</para> +<para> +<!-- .LP --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> + first_valuator + num_valuators, +</literallayout> +</para> +<para> +<!-- .LP --> +<function>XChangeDeviceControl</function> +can generate +<function>BadMatch</function> +and +<function>BadValue</function> +errors. +</para> +</sect3> +<sect3 id="Selecting_Extension_Device_Events"> +<title>Selecting Extension Device Events</title> +<!-- .XS --> +<!-- (SN Selecting Extension Device Events --> +<!-- .XE --> +<para> +<!-- .LP --> +To select device input events, use +<function>XSelectExtensionEvent .</function> +The parameters passed are a pointer to +a list of classes that define the desired event types and devices, a count +of the number of elements in the list, and the ID of the window from which +events are desired. +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSelectExtensionEvent</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> window</parameter></paramdef> + <paramdef>XEventClass<parameter> *event_list</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of the window from which the client wishes to receive events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_list</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an array of event classes +that specify which events are desired. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the event_list. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSelectExtensionEvent</function> +requests the server to send events that match the events and +devices described by the event list and that come from the requested +window. +The elements of the +<function>XEventClass</function> +array are the event_class values +obtained by invoking a macro with the pointer to an +<function>XDevice</function> +structure returned by the +<function>XOpenDevice</function> +request. +For example, the +<function>DeviceKeyPress</function> +macro would return the +<function>XEventClass</function> +for +<function>DeviceKeyPress</function> +events from the specified device if it were invoked in the following form: +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> + DeviceKeyPress (XDevice *device, event_type, event_class) +</literallayout> +</para> +<para> +<!-- .LP --> +Macros are defined for the following event classes: +<literallayout class="monospaced"> +<function>DeviceKeyPress</function> +<function>DeviceKeyRelease</function> +<function>DeviceButtonPress</function> +<function>DeviceButtonRelease</function> +<function>DeviceMotionNotify</function> +<function>DeviceFocusIn</function> +<function>DeviceFocusOut</function> +<function>ProximityIn</function> +<function>ProximityOut</function> +<function>DeviceStateNotify</function> +<function>DeviceMappingNotify</function> +<function>ChangeDeviceNotify</function> +<function>DevicePointerMotionHint</function> +<function>DeviceButton1Motion </function> +<function>DeviceButton2Motion</function> +<function>DeviceButton3Motion, </function> +<function>DeviceButton4Motion</function> +<function>DeviceButton5Motion</function> +<function>DeviceButtonMotion,</function> +<function>DeviceOwnerGrabButton</function> +<function>DeviceButtonPressGrab</function> +</literallayout> +</para> +<para> +<!-- .LP --> +To get the next available event from within a client program, use the core +<function>XNextEvent</function> +function. This returns the next event whether it +came from a core device or an extension device. +</para> +<para> +<!-- .LP --> +Succeeding +<function>XSelectExtensionEvent</function> +requests using event classes +for the same device as was specified on a previous request will replace +the previous set of selected events from that device with the new set. +</para> +<para> +<!-- .LP --> +<function>XSelectExtensionEvent</function> +can generate +<function>BadAccess , </function> +<function>BadClass ,</function> +<function>BadLength ,</function> +and +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Determining_Selected_Device_Events"> +<title>Determining Selected Device Events</title> +<!-- .XS --> +<!-- (SN Determining Selected Device Events --> +<!-- .XE --> +<para> +<!-- .LP --> +To determine which extension events are currently selected from a given +window, use +<function>XGetSelectedExtensionEvents .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XGetSelectedExtensionEvents</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> window</parameter></paramdef> + <paramdef>int<parameter> *this_client_count</parameter></paramdef> + <paramdef>XEventClass<parameter> **this_client</parameter></paramdef> + <paramdef>int<parameter> *all_clients_count</parameter></paramdef> + <paramdef>XEventClass<parameter> **all_clients</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the ID of the window from which the client wishes to receive events. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>this_client_count</emphasis> + </term> + <listitem> + <para> +Returns the number of elements in the this_client list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>this_client</emphasis> + </term> + <listitem> + <para> +Returns a list of +<function>XEventClasses</function> +that specify which events are +selected by this client. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>all_clients_count</emphasis> + </term> + <listitem> + <para> +Returns the number of elements in the all_clients list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>all_clients</emphasis> + </term> + <listitem> + <para> +Returns a list of +<function>XEventClasses</function> +that specify which events are +selected by all clients. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetSelectedExtensionEvents</function> +returns pointers to two event class arrays. +One lists the extension events selected by this client from +the specified window. The other lists the extension events selected by +all clients from the specified window. This information is analogous +to that returned in your_event_mask and all_event_masks of the +<function>XWindowAttributes</function> +structure when an +<function>XGetWindowAttributes</function> +request is made. +To free the two arrays returned by this function, use +<function>XFree .</function> +</para> +<para> +<!-- .LP --> +<function>XGetSelectedExtensionEvents</function> +can generate +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Controlling_Event_Propagation"> +<title>Controlling Event Propagation</title> +<!-- .XS --> +<!-- (SN Controlling Event Propagation --> +<!-- .XE --> +<para> +<!-- .LP --> +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> +<!-- .LP --> +Client programs may control event propagation through the use +of the following two functions: +<function>XChangeDeviceDontPropagateList</function> +and +<function>XGetDeviceDontPropagateList . </function> +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XChangeDeviceDontPropagateList</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> window</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> + <paramdef>XEventClass<parameter> *events</parameter></paramdef> + <paramdef>int<parameter> mode</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the desired window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the events list. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>events</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the list of XEventClasses. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode</emphasis> + </term> + <listitem> + <para> +Specifies the mode. You can pass +<function>AddToList</function> +or +<function>DeleteFromList .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XChangeDeviceDontPropagateList</function> +adds an event to or deletes an event from the do_not_propagate list +of extension events for the specified window. +There is one list per window, and the list remains for the life of the window. +The list is not altered if a client that changed the list terminates. +</para> +<para> +<!-- .LP --> +Suppression of event propagation is not allowed for all events. If a +specified +<function>XEventClass</function> +is invalid because suppression of that event is not allowed, a +<function>BadClass</function> +error results. +</para> +<para> +<!-- .LP --> +<function>XChangeDeviceDontPropagateList</function> +can generate +<function>BadClass ,</function> +<function>BadMode ,</function> +and +<function>BadWindow</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XEventClass * <function> XGetDeviceDontPropagateList</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>Window<parameter> window</parameter></paramdef> + <paramdef>int<parameter> *event_count</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the desired window. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Returns the number of elements in the array returned by this function. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceDontPropagateList</function> +allows a client to determine the do_not_propagate list of extension events +for the specified window. +It returns an array of +<function>XEventClass ,</function> +each +<function>XEventClass</function> +representing a device/event type pair. +To free the data returned by this function, use +<function>XFree .</function> +</para> +<para> +<!-- .LP --> +<function>XGetDeviceDontPropagateList</function> +can generate +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Sending_an_Event"> +<title>Sending an Event</title> +<!-- .XS --> +<!-- (SN Sending an Event --> +<!-- .XE --> +<para> +<!-- .LP --> +To send an extension event to another client, use +<function>XSendExtensionEvent .</function> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>int <function> XSendExtensionEvent</function></funcdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Window<parameter> window</parameter></paramdef> + <paramdef>Bool<parameter> propagate</parameter></paramdef> + <paramdef>int<parameter> event_count</parameter></paramdef> + <paramdef>XEventClass<parameter> *event_list</parameter></paramdef> + <paramdef>XEvent<parameter> *event</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the device whose ID is recorded in the event. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>window</emphasis> + </term> + <listitem> + <para> +Specifies the destination window ID. You can pass a window ID, +<function>PointerWindow</function> +or +<function>InputFocus .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>propagate</emphasis> + </term> + <listitem> + <para> +Specifies a boolean value that is either +<function>True</function> +or +<function>False .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_count</emphasis> + </term> + <listitem> + <para> +Specifies the number of elements in the event_list array. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event_list</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to an array of +<function>XEventClass .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>event</emphasis> + </term> + <listitem> + <para> +Specifies a pointer to the event that is to be sent. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XSendExtensionEvent</function> +identifies the destination window, determines which clients should receive +the specified event, and ignores any active grabs. +It requires a list of +<function>XEventClass</function> +to be specified. +These are obtained by opening an input device with the +<function>XOpenDevice</function> +request. +</para> +<para> +<!-- .LP --> +<function>XSendExtensionEvent</function> +uses the window argument to identify the destination window as follows: +</para> +<itemizedlist> + <listitem> + <para> +If you pass +<function>PointerWindow ,</function> +the destination window is the window that contains the pointer. + </para> + </listitem> + <listitem> + <para> +If you pass +<function>InputFocus</function> +and if the focus window contains the pointer, +the destination window is the window that contains the pointer. +If the focus window does not contain the pointer, +the destination window is the focus window. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +To determine which clients should receive the specified events, +<function>XSendExtensionEvent</function> +uses the propagate argument as follows: +</para> +<itemizedlist> + <listitem> + <para> +If propagate is +<function>False ,</function> +the event is sent to every client selecting +from the destination window +any of the events specified in the event_list array. + </para> + </listitem> + <listitem> + <para> +If propagate is +<function>True </function> +and no clients have selected from the destination window +any of the events specified in the event_list array, the destination is +replaced with the closest ancestor of destination for which some client +has selected one of the specified events and for which no intervening +window has that event in its do_not_propagate mask. +If no such window exists, +or if the window is an ancestor of the focus window, and +<function>InputFocus</function> +was originally specified as the destination, +the event is not sent to any clients. Otherwise, the event is reported to every +client selecting on the final destination any of the events specified +in event_list. + </para> + </listitem> +</itemizedlist> +<para> +<!-- .LP --> +The event in the +<function>XEvent</function> +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 +<function>True</function> +in the forwarded event and to set the sequence number in the event correctly. +</para> +<para> +<!-- .LP --> +<function>XSendExtensionEvent</function> +returns zero if the conversion-to-wire protocol failed; +otherwise, it returns nonzero. +</para> +<para> +<!-- .LP --> +<function>XSendExtensionEvent</function> +can generate +<function>BadClass ,</function> +<function>BadDevice ,</function> +<function>BadValue ,</function> +and +<function>BadWindow</function> +errors. +</para> +</sect3> +<sect3 id="Getting_Motion_History"> +<title>Getting Motion History</title> +<!-- .XS --> +<!-- (SN Getting Motion History --> +<!-- .XE --> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>XDeviceTimeCoord * <function> XGetDeviceMotionEvents</function></funcdef> + <paramdef><parameter> axis_count_return)</parameter></paramdef> + <paramdef>Display<parameter> *display</parameter></paramdef> + <paramdef>XDevice<parameter> *device</parameter></paramdef> + <paramdef>Timestart,<parameter> stop</parameter></paramdef> + <paramdef>int<parameter> *nevents_return</parameter></paramdef> + <paramdef>int<parameter> *mode_return</parameter></paramdef> + <paramdef>int<parameter> *axis_count_return</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>display</emphasis> + </term> + <listitem> + <para> +Specifies the connection to the X server. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>device</emphasis> + </term> + <listitem> + <para> +Specifies the desired device. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>start</emphasis> + </term> + <listitem> + <para> +Specifies the start time. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>stop</emphasis> + </term> + <listitem> + <para> +Specifies the stop time. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>nevents_return</emphasis> + </term> + <listitem> + <para> +Returns the number of positions in the motion buffer returned +for this request. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>mode_return</emphasis> + </term> + <listitem> + <para> +Returns the mode of the nevents information. +The mode will be one of the following: +<function>Absolute</function> +or +<function>Relative .</function> + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <emphasis remap='I'>axis_count_return</emphasis> + </term> + <listitem> + <para> +Returns the number of axes reported in each of the positions returned. + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XGetDeviceMotionEvents</function> +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> +<!-- .LP --> +The return type for this function is an +<function>XDeviceTimeCoord</function> +structure, which is defined as follows: +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<literallayout class="monospaced"> +<!-- .TA .5i --> +<!-- .ta .5i --> +typedef struct { + Time time; + unsigned int *data; +} XDeviceTimeCoord; +</literallayout> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +The data member is a pointer to an array of data items. +Each item is of type int, 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> +<!-- .LP --> +The value of the data items depends on the mode of the device. +The mode is returned in the mode variable. If the +mode is +<function>Absolute ,</function> +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 value for each axis is reported in +the max_val member of the +<function>XAxisInfo</function> +structure, which is part of the information returned by the +<function>XListInputDevices</function> +request. +</para> +<para> +<!-- .LP --> +If the mode is +<function>Relative ,</function> +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> +<para> +<!-- .LP --> +Consecutive calls to +<function>XGetDeviceMotionEvents</function> +can return data of different modes, that is, if +some client program has changed the mode of the device via an +<function>XSetDeviceMode</function> +request. +</para> +<para> +<!-- .LP --> +<function>XGetDeviceMotionEvents</function> +can generate +<function>BadDevice</function> +and +<function>BadMatch</function> +errors. +<!-- .sp --> +</para> +<para> +<!-- .LP --> +To free the data returned by +<function>XGetDeviceMotionEvents ,</function> +use +<function>XFreeDeviceMotionEvents .</function> +</para> +<para> +<!-- .LP --> +<!-- .sM --> +<funcsynopsis> +<funcprototype> + <funcdef>void <function> XFreeDeviceMotionEvents</function></funcdef> + <paramdef>XDeviceTimeCoord<parameter> *events</parameter></paramdef> +</funcprototype> +</funcsynopsis> +<!-- .FN --> +<variablelist> + <varlistentry> + <term> + <emphasis remap='I'>events</emphasis> + </term> + <listitem> + <para> +Specifies the pointer to the +<function>XDeviceTimeCoord</function> +array returned by a previous call to +<function>XGetDeviceMotionEvents .</function> + </para> + </listitem> + </varlistentry> +</variablelist> +</para> +<para> +<!-- .LP --> +<!-- .eM --> +<function>XFreeDeviceMotionEvents</function> +frees the specified array of motion information. +<!-- .\" --> +<!-- .\" --> +<!-- .\" Appendicies --> +<!-- .\" --> +<!-- .\" --> +<!-- .bp --> +<!-- .ds Ch ~ --> +<!-- .sp 1 --> +<!-- .ce 3 --> +<function>Appendix A</function> +<!-- .XS --> +<!-- (SN Appendix A --> +<!-- .XE --> +</para> +<para> +<!-- .LP --> +The following information is contained in the <function><X11/extensions/XInput.h></function> +and <function><X11/extensions/XI.h></function> header files: +<literallayout class="monospaced"> +<!-- .cs CW 20 --> + +<!-- .ps 8 --> +/* Definitions used by the library and client */ + +#ifndef _XINPUT_H_ +#define _XINPUT_H_ + +#ifndef _XLIB_H_ +#include <X11/Xlib.h> +#endif + +#ifndef _XI_H_ +#include "XI.h" +#endif + +#define _deviceKeyPress 0 +#define _deviceKeyRelease 1 + +#define _deviceButtonPress 0 +#define _deviceButtonRelease 1 + +#define _deviceMotionNotify 0 + +#define _deviceFocusIn 0 +#define _deviceFocusOut 1 + +#define _proximityIn 0 +#define _proximityOut 1 + +#define _deviceStateNotify 0 +#define _deviceMappingNotify 1 +#define _changeDeviceNotify 2 + +#define FindTypeAndClass(d, type, class, classid, offset) \ + { int i; XInputClassInfo *ip; \ + type = 0; class = 0; \ + for (i=0, ip= ((XDevice *) d)->classes; \ + i< ((XDevice *) d)->num_classes; \ + i++, ip++) \ + if (ip->input_class == classid) \ + {type = ip->event_type_base + offset; \ + class = ((XDevice *) d)->device_id << 8 | type;}} + +#define DeviceKeyPress(d, type, class) \ + FindTypeAndClass(d, type, class, KeyClass, _deviceKeyPress) + +#define DeviceKeyRelease(d, type, class) \ + FindTypeAndClass(d, type, class, KeyClass, _deviceKeyRelease) + +#define DeviceButtonPress(d, type, class) \ + FindTypeAndClass(d, type, class, ButtonClass, _deviceButtonPress) + +#define DeviceButtonRelease(d, type, class) \ + FindTypeAndClass(d, type, class, ButtonClass, _deviceButtonRelease) + +#define DeviceMotionNotify(d, type, class) \ + FindTypeAndClass(d, type, class, ValuatorClass, _deviceMotionNotify) + +#define DeviceFocusIn(d, type, class) \ + FindTypeAndClass(d, type, class, FocusClass, _deviceFocusIn) + +#define DeviceFocusOut(d, type, class) \ + FindTypeAndClass(d, type, class, FocusClass, _deviceFocusOut) + +#define ProximityIn(d, type, class) \ + FindTypeAndClass(d, type, class, ProximityClass, _proximityIn) + +#define ProximityOut(d, type, class) \ + FindTypeAndClass(d, type, class, ProximityClass, _proximityOut) + +#define DeviceStateNotify(d, type, class) \ + FindTypeAndClass(d, type, class, OtherClass, _deviceStateNotify) + +#define DeviceMappingNotify(d, type, class) \ + FindTypeAndClass(d, type, class, OtherClass, _deviceMappingNotify) + +#define ChangeDeviceNotify(d, type, class) \ + FindTypeAndClass(d, type, class, OtherClass, _changeDeviceNotify) + +#define DevicePointerMotionHint(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _devicePointerMotionHint;} + +#define DeviceButton1Motion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButton1Motion;} + +#define DeviceButton2Motion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButton2Motion;} + +#define DeviceButton3Motion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButton3Motion;} + +#define DeviceButton4Motion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButton4Motion;} + +#define DeviceButton5Motion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButton5Motion;} + +#define DeviceButtonMotion(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButtonMotion;} + +#define DeviceOwnerGrabButton(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceOwnerGrabButton;} + +#define DeviceButtonPressGrab(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _deviceButtonGrab;} + +#define NoExtensionEvent(d, type, class) \ + { class = ((XDevice *) d)->device_id << 8 | _noExtensionEvent;} + +#define BadDevice(dpy, error) _xibaddevice(dpy, &error) + +#define BadClass(dpy, error) _xibadclass(dpy, &error) + +#define BadEvent(dpy, error) _xibadevent(dpy, &error) + +#define BadMode(dpy, error) _xibadmode(dpy, &error) + +#define DeviceBusy(dpy, error) _xidevicebusy(dpy, &error) + +/*************************************************************** + * + * DeviceKey events. These events are sent by input devices that + * support input class Keys. + * The location of the X pointer is reported in the coordinate + * fields of the x,y and x_root,y_root fields. + * + */ + +typedef struct + { + int type; /* of event */ + unsigned long serial; /* # of last request processed */ + Bool send_event; /* true if from SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window event occured on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int keycode; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; + } XDeviceKeyEvent; + +typedef XDeviceKeyEvent XDeviceKeyPressedEvent; +typedef XDeviceKeyEvent XDeviceKeyReleasedEvent; + +/******************************************************************* + * + * DeviceButton events. These events are sent by extension devices + * that support input class Buttons. + * + */ + +typedef struct { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window that the event occured on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + unsigned int button; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; + } XDeviceButtonEvent; + +typedef XDeviceButtonEvent XDeviceButtonPressedEvent; +typedef XDeviceButtonEvent XDeviceButtonReleasedEvent; + +/******************************************************************* + * + * DeviceMotionNotify event. These events are sent by extension devices + * that support input class Valuators. + * + */ + +typedef struct + { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + Window root; /* root window that the event occured on */ + Window subwindow; /* child window */ + Time time; /* milliseconds */ + int x, y; /* x, y coordinates in event window */ + int x_root; /* coordinates relative to root */ + int y_root; /* coordinates relative to root */ + unsigned int state; /* key or button mask */ + char is_hint; /* detail */ + Bool same_screen; /* same screen flag */ + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; + } XDeviceMotionEvent; + +/******************************************************************* + * + * DeviceFocusChange events. These events are sent when the focus + * of an extension device that can be focused is changed. + * + */ + +typedef struct + { + int type; /* of event */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* "event" window reported relative to */ + XID deviceid; + int mode; /* NotifyNormal, NotifyGrab, NotifyUngrab */ + int detail; + /* + * NotifyAncestor, NotifyVirtual, NotifyInferior, + * NotifyNonLinear,NotifyNonLinearVirtual, NotifyPointer, + * NotifyPointerRoot, NotifyDetailNone + */ + Time time; + } XDeviceFocusChangeEvent; + +typedef XDeviceFocusChangeEvent XDeviceFocusInEvent; +typedef XDeviceFocusChangeEvent XDeviceFocusOutEvent; + +/******************************************************************* + * + * ProximityNotify events. These events are sent by those absolute + * positioning devices that are capable of generating proximity information. + * + */ + +typedef struct + { + int type; /* ProximityIn or ProximityOut */ + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + XID deviceid; + Window root; + Window subwindow; + Time time; + int x, y; + int x_root, y_root; + unsigned int state; + Bool same_screen; + unsigned int device_state; /* device key or button mask */ + unsigned char axes_count; + unsigned char first_axis; + int axis_data[6]; + } XProximityNotifyEvent; +typedef XProximityNotifyEvent XProximityInEvent; +typedef XProximityNotifyEvent XProximityOutEvent; + +/******************************************************************* + * + * DeviceStateNotify events are generated on EnterWindow and FocusIn + * for those clients who have selected DeviceState. + * + */ + +typedef struct + { + unsigned char class; + unsigned char length; + } XInputClass; + +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; + XID deviceid; + Time time; + int num_classes; + char data[64]; +} XDeviceStateNotifyEvent; + +typedef struct { + unsigned char class; + unsigned char length; + unsigned char num_valuators; + unsigned char mode; + int valuators[6]; +} XValuatorStatus; + +typedef struct { + unsigned char class; + unsigned char length; + short num_keys; + char keys[32]; +} XKeyStatus; + +typedef struct { + unsigned char class; + unsigned char length; + short num_buttons; + char buttons[32]; +} XButtonStatus; + +/******************************************************************* + * + * DeviceMappingNotify event. This event is sent when the key mapping, + * modifier mapping, or button mapping of an extension device is changed. + * + */ + +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* unused */ + XID deviceid; + Time time; + int request; /* one of MappingModifier, MappingKeyboard, + MappingPointer */ + int first_keycode;/* first keycode */ + int count; /* defines range of change w. first_keycode*/ +} XDeviceMappingEvent; + +/******************************************************************* + * + * ChangeDeviceNotify event. This event is sent when an + * XChangeKeyboard or XChangePointer request is made. + * + */ + +typedef struct { + int type; + unsigned long serial; /* # of last request processed by server */ + Bool send_event; /* true if this came from a SendEvent request */ + Display *display; /* Display the event was read from */ + Window window; /* unused */ + XID deviceid; + Time time; + int request; /* NewPointer or NewKeyboard */ +} XChangeDeviceNotifyEvent; + +/******************************************************************* + * + * Control structures for input devices that support input class + * Feedback. These are used by the XGetFeedbackControl and + * XChangeFeedbackControl functions. + * + */ + +typedef struct { + XID class; + int length; + XID id; +} XFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int click; + int percent; + int pitch; + int duration; + int led_mask; + int global_auto_repeat; + char auto_repeats[32]; +} XKbdFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int accelNum; + int accelDenom; + int threshold; +} XPtrFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int resolution; + int minVal; + int maxVal; +} XIntegerFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int max_symbols; + int num_syms_supported; + KeySym *syms_supported; +} XStringFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int percent; + int pitch; + int duration; +} XBellFeedbackState; + +typedef struct { + XID class; + int length; + XID id; + int led_values; + int led_mask; +} XLedFeedbackState; + +typedef struct { + XID class; + int length; + XID id; +} XFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int accelNum; + int accelDenom; + int threshold; +} XPtrFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int click; + int percent; + int pitch; + int duration; + int led_mask; + int led_value; + int key; + int auto_repeat_mode; +} XKbdFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int num_keysyms; + KeySym *syms_to_display; +} XStringFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int int_to_display; +} XIntegerFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int percent; + int pitch; + int duration; +} XBellFeedbackControl; + +typedef struct { + XID class; + int length; + XID id; + int led_mask; + int led_values; +} XLedFeedbackControl; + +/******************************************************************* + * + * Device control structures. + * + */ + +typedef struct { + XID control; + int length; +} XDeviceControl; + +typedef struct { + XID control; + int length; + int first_valuator; + int num_valuators; + int *resolutions; +} XDeviceResolutionControl; + +typedef struct { + XID control; + int length; + int num_valuators; + int *resolutions; + int *min_resolutions; + int *max_resolutions; +} XDeviceResolutionState; + +/******************************************************************* + * + * An array of XDeviceList structures is returned by the + * XListInputDevices function. Each entry contains information + * about one input device. Among that information is an array of + * pointers to structures that describe the characteristics of + * the input device. + * + */ + +typedef struct _XAnyClassinfo *XAnyClassPtr; + +typedef struct _XAnyClassinfo { + XID class; + int length; + } XAnyClassInfo; + +typedef struct _XDeviceInfo *XDeviceInfoPtr; + +typedef struct _XDeviceInfo + { + XID id; + Atom type; + char *name; + int num_classes; + int use; + XAnyClassPtr inputclassinfo; + } XDeviceInfo; + +typedef struct _XKeyInfo *XKeyInfoPtr; + +typedef struct _XKeyInfo + { + XID class; + int length; + unsigned short min_keycode; + unsigned short max_keycode; + unsigned short num_keys; + } XKeyInfo; + +typedef struct _XButtonInfo *XButtonInfoPtr; + +typedef struct _XButtonInfo { + XID class; + int length; + short num_buttons; + } XButtonInfo; + +typedef struct _XAxisInfo *XAxisInfoPtr; + +typedef struct _XAxisInfo { + int resolution; + int min_value; + int max_value; + } XAxisInfo; + +typedef struct _XValuatorInfo *XValuatorInfoPtr; + +typedef struct _XValuatorInfo + { + XID class; + int length; + unsigned char num_axes; + unsigned char mode; + unsigned long motion_buffer; + XAxisInfoPtr axes; + } XValuatorInfo; + + +/******************************************************************* + * + * An XDevice structure is returned by the XOpenDevice function. + * It contains an array of pointers to XInputClassInfo structures. + * Each contains information about a class of input supported by the + * device, including a pointer to an array of data for each type of event + * the device reports. + * + */ + + +typedef struct { + unsigned char input_class; + unsigned char event_type_base; +} XInputClassInfo; + +typedef struct { + XID device_id; + int num_classes; + XInputClassInfo *classes; +} XDevice; + + +/******************************************************************* + * + * The following structure is used to return information for the + * XGetSelectedExtensionEvents function. + * + */ + +typedef struct { + XEventClass event_type; + XID device; +} XEventList; + +/******************************************************************* + * + * The following structure is used to return motion history data from + * an input device that supports the input class Valuators. + * This information is returned by the XGetDeviceMotionEvents function. + * + */ + +typedef struct { + Time time; + int *data; +} XDeviceTimeCoord; + + +/******************************************************************* + * + * Device state structure. + * This is returned by the XQueryDeviceState request. + * + */ + +typedef struct { + XID device_id; + int num_classes; + XInputClass *data; +} XDeviceState; + +/******************************************************************* + * + * Note that the mode field is a bitfield that reports the Proximity + * status of the device as well as the mode. The mode field should + * be OR'd with the mask DeviceMode and compared with the values + * Absolute and Relative to determine the mode, and should be OR'd + * with the mask ProximityState and compared with the values InProximity + * and OutOfProximity to determine the proximity state. + * + */ + +typedef struct { + unsigned char class; + unsigned char length; + unsigned char num_valuators; + unsigned char mode; + int *valuators; +} XValuatorState; + +typedef struct { + unsigned char class; + unsigned char length; + short num_keys; + char keys[32]; +} XKeyState; + +typedef struct { + unsigned char class; + unsigned char length; + short num_buttons; + char buttons[32]; +} XButtonState; + +/******************************************************************* + * + * Function definitions. + * + */ + +_XFUNCPROTOBEGIN + +extern int XChangeKeyboardDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */ +#endif +); + +extern int XChangePointerDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* xaxis */, + int /* yaxis */ +#endif +); + +extern int XGrabDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Window /* grab_window */, + Bool /* ownerEvents */, + int /* event count */, + XEventClass* /* event_list */, + int /* this_device_mode */, + int /* other_devices_mode */, + Time /* time */ +#endif +); + +extern int XUngrabDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Time /* time */ +#endif +); + +extern int XGrabDeviceKey( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned int /* key */, + unsigned int /* modifiers */, + XDevice* /* modifier_device */, + Window /* grab_window */, + Bool /* owner_events */, + unsigned int /* event_count */, + XEventClass* /* event_list */, + int /* this_device_mode */, + int /* other_devices_mode */ +#endif +); + +extern int XUngrabDeviceKey( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned int /* key */, + unsigned int /* modifiers */, + XDevice* /* modifier_dev */, + Window /* grab_window */ +#endif +); + +extern int XGrabDeviceButton( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned int /* button */, + unsigned int /* modifiers */, + XDevice* /* modifier_device */, + Window /* grab_window */, + Bool /* owner_events */, + unsigned int /* event_count */, + XEventClass* /* event_list */, + int /* this_device_mode */, + int /* other_devices_mode */ +#endif +); + +extern int XUngrabDeviceButton( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned int /* button */, + unsigned int /* modifiers */, + XDevice* /* modifier_dev */, + Window /* grab_window */ +#endif +); + +extern int XAllowDeviceEvents( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* event_mode */, + Time /* time */ +#endif +); + +extern int XGetDeviceFocus( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Window* /* focus */, + int* /* revert_to */, + Time* /* time */ +#endif +); + +extern int XSetDeviceFocus( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Window /* focus */, + int /* revert_to */, + Time /* time */ +#endif +); + +extern XFeedbackState *XGetFeedbackControl( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int* /* num_feedbacks */ +#endif +); + +extern int XFreeFeedbackList( +#if NeedFunctionPrototypes + XFeedbackState* /* list */ +#endif +); + +extern int XChangeFeedbackControl( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned long /* mask */, + XFeedbackControl* /* f */ +#endif +); + +extern int XDeviceBell( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + XID /* feedbackclass */, + XID /* feedbackid */, + int /* percent */ +#endif +); + +extern KeySym *XGetDeviceKeyMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, +#if NeedWidePrototypes + unsigned int /* first */, +#else + KeyCode /* first */, +#endif + int /* keycount */, + int* /* syms_per_code */ +#endif +); + +extern int XChangeDeviceKeyMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* first */, + int /* syms_per_code */, + KeySym* /* keysyms */, + int /* count */ +#endif +); + +extern XModifierKeymap *XGetDeviceModifierMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */ +#endif +); + +extern int XSetDeviceModifierMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + XModifierKeymap* /* modmap */ +#endif +); + +extern int XSetDeviceButtonMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned char* /* map[] */, + int /* nmap */ +#endif +); + +extern int XGetDeviceButtonMapping( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + unsigned char* /* map[] */, + unsigned int /* nmap */ +#endif +); + +extern XDeviceState *XQueryDeviceState( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */ +#endif +); + +extern int XFreeDeviceState( +#if NeedFunctionPrototypes + XDeviceState* /* list */ +#endif +); + +extern XExtensionVersion *XGetExtensionVersion( +#if NeedFunctionPrototypes + Display* /* display */, + _Xconst char* /* name */ +#endif +); + +extern XDeviceInfo *XListInputDevices( +#if NeedFunctionPrototypes + Display* /* display */, + int* /* ndevices */ +#endif +); + +extern int XFreeDeviceList( +#if NeedFunctionPrototypes + XDeviceInfo* /* list */ +#endif +); + +extern XDevice *XOpenDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XID /* id */ +#endif +); + +extern int XCloseDevice( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */ +#endif +); + +extern int XSetDeviceMode( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* mode */ +#endif +); + +extern int XSetDeviceValuators( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int* /* valuators */, + int /* first_valuator */, + int /* num_valuators */ +#endif +); + +extern XDeviceControl *XGetDeviceControl( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* control */ +#endif +); + +extern int XChangeDeviceControl( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + int /* control */, + XDeviceControl* /* d */ +#endif +); + +extern int XSelectExtensionEvent( +#if NeedFunctionPrototypes + Display* /* display */, + Window /* w */, + XEventClass* /* event_list */, + int /* count */ +#endif +); + +extern int XGetSelectedExtensionEvents( +#if NeedFunctionPrototypes + Display* /* display */, + Window /* w */, + int* /* this_client_count */, + XEventClass** /* this_client_list */, + int* /* all_clients_count */, + XEventClass** /* all_clients_list */ +#endif +); + +extern int XChangeDeviceDontPropagateList( +#if NeedFunctionPrototypes + Display* /* display */, + Window /* window */, + int /* count */, + XEventClass* /* events */, + int /* mode */ +#endif +); + +extern XEventClass *XGetDeviceDontPropagateList( +#if NeedFunctionPrototypes + Display* /* display */, + Window /* window */, + int* /* count */ +#endif +); + +extern Status XSendExtensionEvent( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Window /* dest */, + Bool /* prop */, + int /* count */, + XEventClass* /* list */, + XEvent* /* event */ +#endif +); + +extern XDeviceTimeCoord *XGetDeviceMotionEvents( +#if NeedFunctionPrototypes + Display* /* display */, + XDevice* /* device */, + Time /* start */, + Time /* stop */, + int* /* nEvents */, + int* /* mode */, + int* /* axis_count */ +#endif +); + +extern int XFreeDeviceMotionEvents( +#if NeedFunctionPrototypes + XDeviceTimeCoord* /* events */ +#endif +); + +extern int XFreeDeviceControl( +#if NeedFunctionPrototypes + XDeviceControl* /* control */ +#endif +); + +_XFUNCPROTOEND + +#endif /* _XINPUT_H_ */ + +/* Definitions used by the server, library and client */ + +#ifndef _XI_H_ + +#define _XI_H_ + +#define sz_xGetExtensionVersionReq 8 +#define sz_xGetExtensionVersionReply 32 +#define sz_xListInputDevicesReq 4 +#define sz_xListInputDevicesReply 32 +#define sz_xOpenDeviceReq 8 +#define sz_xOpenDeviceReply 32 +#define sz_xCloseDeviceReq 8 +#define sz_xSetDeviceModeReq 8 +#define sz_xSetDeviceModeReply 32 +#define sz_xSelectExtensionEventReq 12 +#define sz_xGetSelectedExtensionEventsReq 8 +#define sz_xGetSelectedExtensionEventsReply 32 +#define sz_xChangeDeviceDontPropagateListReq 12 +#define sz_xGetDeviceDontPropagateListReq 8 +#define sz_xGetDeviceDontPropagateListReply 32 +#define sz_xGetDeviceMotionEventsReq 16 +#define sz_xGetDeviceMotionEventsReply 32 +#define sz_xChangeKeyboardDeviceReq 8 +#define sz_xChangeKeyboardDeviceReply 32 +#define sz_xChangePointerDeviceReq 8 +#define sz_xChangePointerDeviceReply 32 +#define sz_xGrabDeviceReq 20 +#define sz_xGrabDeviceReply 32 +#define sz_xUngrabDeviceReq 12 +#define sz_xGrabDeviceKeyReq 20 +#define sz_xGrabDeviceKeyReply 32 +#define sz_xUngrabDeviceKeyReq 16 +#define sz_xGrabDeviceButtonReq 20 +#define sz_xGrabDeviceButtonReply 32 +#define sz_xUngrabDeviceButtonReq 16 +#define sz_xAllowDeviceEventsReq 12 +#define sz_xGetDeviceFocusReq 8 +#define sz_xGetDeviceFocusReply 32 +#define sz_xSetDeviceFocusReq 16 +#define sz_xGetFeedbackControlReq 8 +#define sz_xGetFeedbackControlReply 32 +#define sz_xChangeFeedbackControlReq 12 +#define sz_xGetDeviceKeyMappingReq 8 +#define sz_xGetDeviceKeyMappingReply 32 +#define sz_xChangeDeviceKeyMappingReq 8 +#define sz_xGetDeviceModifierMappingReq 8 +#define sz_xSetDeviceModifierMappingReq 8 +#define sz_xSetDeviceModifierMappingReply 32 +#define sz_xGetDeviceButtonMappingReq 8 +#define sz_xGetDeviceButtonMappingReply 32 +#define sz_xSetDeviceButtonMappingReq 8 +#define sz_xSetDeviceButtonMappingReply 32 +#define sz_xQueryDeviceStateReq 8 +#define sz_xQueryDeviceStateReply 32 +#define sz_xSendExtensionEventReq 16 +#define sz_xDeviceBellReq 8 +#define sz_xSetDeviceValuatorsReq 8 +#define sz_xSetDeviceValuatorsReply 32 +#define sz_xGetDeviceControlReq 8 +#define sz_xGetDeviceControlReply 32 +#define sz_xChangeDeviceControlReq 8 +#define sz_xChangeDeviceControlReply 32 + +#define INAME "XInputExtension" + +#define XI_KEYBOARD "KEYBOARD" +#define XI_MOUSE "MOUSE" +#define XI_TABLET "TABLET" +#define XI_TOUCHSCREEN "TOUCHSCREEN" +#define XI_TOUCHPAD "TOUCHPAD" +#define XI_BARCODE "BARCODE" +#define XI_BUTTONBOX "BUTTONBOX" +#define XI_KNOB_BOX "KNOB_BOX" +#define XI_ONE_KNOB "ONE_KNOB" +#define XI_NINE_KNOB "NINE_KNOB" +#define XI_TRACKBALL "TRACKBALL" +#define XI_QUADRATURE "QUADRATURE" +#define XI_ID_MODULE "ID_MODULE" +#define XI_SPACEBALL "SPACEBALL" +#define XI_DATAGLOVE "DATAGLOVE" +#define XI_EYETRACKER "EYETRACKER" +#define XI_CURSORKEYS "CURSORKEYS" +#define XI_FOOTMOUSE "FOOTMOUSE" + +#define Dont_Check 0 +#define XInput_Initial_Release 1 +#define XInput_Add_XDeviceBell 2 +#define XInput_Add_XSetDeviceValuators 3 +#define XInput_Add_XChangeDeviceControl 4 + +#define XI_Absent 0 +#define XI_Present 1 + +#define XI_Initial_Release_Major 1 +#define XI_Initial_Release_Minor 0 + +#define XI_Add_XDeviceBell_Major 1 +#define XI_Add_XDeviceBell_Minor 1 + +#define XI_Add_XSetDeviceValuators_Major 1 +#define XI_Add_XSetDeviceValuators_Minor 2 + +#define XI_Add_XChangeDeviceControl_Major 1 +#define XI_Add_XChangeDeviceControl_Minor 3 + +#define DEVICE_RESOLUTION 1 + +#define NoSuchExtension 1 + +#define COUNT 0 +#define CREATE 1 + +#define NewPointer 0 +#define NewKeyboard 1 + +#define XPOINTER 0 +#define XKEYBOARD 1 + +#define UseXKeyboard 0xFF + +#define IsXPointer 0 +#define IsXKeyboard 1 +#define IsXExtensionDevice 2 + +#define AsyncThisDevice 0 +#define SyncThisDevice 1 +#define ReplayThisDevice 2 +#define AsyncOtherDevices 3 +#define AsyncAll 4 +#define SyncAll 5 + +#define FollowKeyboard 3 +#define RevertToFollowKeyboard 3 + +#define DvAccelNum (1L << 0) +#define DvAccelDenom (1L << 1) +#define DvThreshold (1L << 2) + +#define DvKeyClickPercent (1L<<0) +#define DvPercent (1L<<1) +#define DvPitch (1L<<2) +#define DvDuration (1L<<3) +#define DvLed (1L<<4) +#define DvLedMode (1L<<5) +#define DvKey (1L<<6) +#define DvAutoRepeatMode (1L<<7) + +#define DvString (1L << 0) + +#define DvInteger (1L << 0) + +#define DeviceMode (1L << 0) +#define Relative 0 +#define Absolute 1 + +#define ProximityState (1L << 1) +#define InProximity (0L << 1) +#define OutOfProximity (1L << 1) + +#define AddToList 0 +#define DeleteFromList 1 + +#define KeyClass 0 +#define ButtonClass 1 +#define ValuatorClass 2 +#define FeedbackClass 3 +#define ProximityClass 4 +#define FocusClass 5 +#define OtherClass 6 + +#define KbdFeedbackClass 0 +#define PtrFeedbackClass 1 +#define StringFeedbackClass 2 +#define IntegerFeedbackClass 3 +#define LedFeedbackClass 4 +#define BellFeedbackClass 5 + +#define _devicePointerMotionHint 0 +#define _deviceButton1Motion 1 +#define _deviceButton2Motion 2 +#define _deviceButton3Motion 3 +#define _deviceButton4Motion 4 +#define _deviceButton5Motion 5 +#define _deviceButtonMotion 6 +#define _deviceButtonGrab 7 +#define _deviceOwnerGrabButton 8 +#define _noExtensionEvent 9 + +#define XI_BadDevice 0 +#define XI_BadEvent 1 +#define XI_BadMode 2 +#define XI_DeviceBusy 3 +#define XI_BadClass 4 + +typedef unsigned long XEventClass; + +/******************************************************************* + * + * Extension version structure. + * + */ + +typedef struct { + int present; + short major_version; + short minor_version; +} XExtensionVersion; + +#endif /* _XI_H_ */ + +</literallayout> +<!-- .\" print Table of Contents --> +<!-- .if o .bp \" blank page to make count even --> +<!-- .bp 1 --> +<!-- .af PN i --> +<!-- .PX --> + + +</para> +</sect3> +</sect2> +</sect1> +</chapter> |