Chip 2001 August - Disc 2/chip_20018102_hu.iso/linux/X-4.1.0/doc/XiProtocol.TXT

Text File | 2001-06-27 | 125.7 KB | 5,545 lines

     X11 Input Extension Protocol Specification


            Version 1.0

           X Consortium Standard

         X Version 11, Release 6.4
















          Mark Patrick    Ardent Computer

          George Sachs    Hewlett-Packard








































Copyright (C) 1989, 1990, 1991 by Hewlett-Packard Company
and Ardent Computer

Permission to use, copy, modify, and distribute this docu-
mentation 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 pur-
pose of the information in this document.  It is provided
"as is" without express or implied warranty.





Copyright (C) 1989, 1990, 1991, 1992 X Consortium

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documenta-
tion files (the ``Software''), to deal in the Software with-
out 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 fol-
lowing conditions:

The above copyright notice and this permission notice 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 PUR-
POSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE X CONSOR-
TIUM 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.

Except as contained in this notice, the name of the X Con-
sortium 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.



X Window System is a trademark of X Consortium, Inc.





























































1.1.  Input Extension Overview

This document defines an extension to the X11 protocol to
support input devices other than the core X keyboard and
pointer.  An accompanying document defines a corresponding
extension to Xlib (similar extensions for languages other
than C are anticipated).  This first section gives an
overview of the input extension.  The next section defines
the new protocol requests defined by the extension.  We con-
clude with a description of the new input events generated
by the additional input devices.

1.2.  Design Approach

The design approach of the extension is to define requests
and events analogous to the core requests and events. This
allows extension input devices to be individually distin-
guishable from each other and from the core input devices.
These requests and events make use of a device identifier
and support the reporting of n-dimensional motion data as
well as other data that is not reportable via the core input
events.

1.3.  Core Input Devices

The X server core protocol supports two input devices:    a
pointer and a keyboard.  The pointer device has two major
functions.  First, it may be used to generate motion infor-
mation 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 key-
board has been explicitly focused, this cursor also shows
the current location and focus of the X keyboard.

The X keyboard is used to generate input that client pro-
grams can detect.

The X keyboard and X pointer are referred to in this docu-
ment as the core devices, and the input events they generate
(KeyPress, KeyRelease, ButtonPress, ButtonRelease, and
MotionNotify) are known as the core input events.  All other
input devices are referred to as extension input devices and
the input events they generate are referred to as extension
input events.

                Note

     This input extension does not change the behavior
     or functionality of the core input devices, core
     events, or core protocol requests, with the excep-
     tion of the core grab requests.  These requests
     may affect the synchronization of events from
     extension devices.  See the explanation in the



                  1





X Input Extension Protocol Specification    X11, Release 6.4


     section titled "Event Synchronization and Core
     Grabs".


Selection of the physical devices to be initially used by
the server as the core devices is left implementation-depen-
dent.  Requests are defined that allow client programs to
change which physical devices are used as the core devices.

1.4.  Extension Input Devices

The input extension controls access to input devices other
than the X keyboard and X pointer.  It allows client pro-
grams to select input from these devices independently from
each other and independently from the core devices.

A client that wishes to access a specific device must first
determine whether that device is connected to the X server.
This is done through the ListInputDevices request, which
will return a list of all devices that can be opened by the
X server.  A client can then open one or more of these
devices using the OpenDevice request, specify what events
they are interested in receiving, and receive and process
input events from extension devices in the same way as
events from the X keyboard and X pointer.  Input events from
these devices are of extension types (DeviceKeyPress,
DeviceKeyRelease, DeviceButtonPress, DeviceButtonRelease,
DeviceMotionNotify, etc.) and contain a device identifier so
that events of the same type coming from different input
devices can be distinguished.

Any kind of input device may be used as an extension input
device.  Extension input devices may have 0 or more keys, 0
or more buttons, and may report 0 or more axes of motion.
Motion may be reported as relative movements from a previous
position or as an absolute position.  All valuators report-
ing motion information for a given extension input device
must report the same kind of motion information (absolute or
relative).

This extension is designed to accommodate new types of input
devices that may be added in the future.  The protocol
requests that refer to specific characteristics of input
devices organize that information by input classes.  Server
implementors may add new classes of input devices without
changing the protocol requests.  Input classes are unique
numbers registered with the X Consortium.  Each extension
input device may support multiple input classes.

All extension input devices are treated like the core X key-
board in determining their location and focus.    The server
does not track the location of these devices on an individ-
ual basis, and therefore does not echo a cursor to indicate
their current location.  Instead, their location is



                  2





X Input Extension Protocol Specification    X11, Release 6.4


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.

Input events reported by the server to a client are of fixed
size (32 bytes).  In order to represent the change in state
of an input device the extension may need to generate a
sequence of input events.  A client side library (such as
Xlib) will typically take these raw input events and format
them into a form more convenient to the client.

1.4.1.    Event Classes

In the core protocol a client registers interest in receiv-
ing certain input events directed to a window by modifying
that window's event-mask.  Most of the bits in the event
mask are already used to specify interest in core X events.
The input extension specifies a different mechanism by which
a client can express interest in events generated by this
extension.

When a client opens a extension input device via the OpenDe-
vice request, an XDevice structure is returned.  Macros are
provided that extract 32-bit numbers called event classes
from that structure, that a client can use to register
interest in extension events via the SelectExtensionEvent
request.  The event class combines the desired event type
and device id, and may be thought of as the equivalent of
core event masks.

1.4.2.    Input Classes

Some of the input extension requests divide input devices
into classes based on their functionality.  This is intended
to allow new classes of input devices to be defined at a
later time without changing the semantics of these requests.
The following input device classes are currently defined:

     KEY  The device reports key events.

     BUTTON
      The device reports button events.

     VALUATOR
      The device reports valuator data in motion events.

     PROXIMITY
      The device reports proximity events.

     FOCUS
      The device can be focused and reports focus
      events.




                  3





X Input Extension Protocol Specification    X11, Release 6.4


     FEEDBACK
      The device supports feedbacks.

     OTHER
      The ChangeDeviceNotify, DeviceMappingNotify, and
      DeviceStateNotify macros may be invoked passing
      the XDevice structure returned for this device.

Each extension input device may support multiple input
classes.  Additional classes may be added in the future.
Requests that support multiple input classes, such as the
ListInputDevices function that lists all available input
devices, organize the data they return by input class.
Client programs that use these requests should not access
data unless it matches a class defined at the time those
clients were compiled.    In this way, new classes can be
added without forcing existing clients that use these
requests to be recompiled.

2.  Requests

Extension input devices are accessed by client programs
through the use of new protocol requests.  This section sum-
marizes the new requests defined by this extension.  The
syntax and type definitions used below follow the notation
used for the X11 core protocol.

2.1.  Getting the Extension Version

The GetExtensionVersion request returns version information
about the input extension.

GetExtensionVersion
     name: STRING
=>
     present: BOOL
     protocol-major-version: CARD16
     protocol-minor-version: CARD16

     The protocol version numbers returned indicate the ver-
     sion of the input extension supported by the target X
     server.  The version numbers can be compared to con-
     stants defined in the header file XI.h.  Each version
     is a superset of the previous versions.

2.2.  Listing Available Devices

A client that wishes to access a specific device must first
determine whether that device is connected to the X server.
This is done through the ListInputDevices request, which
will return a list of all devices that can be opened by the
X server.

ListInputDevices



                  4





X Input Extension Protocol Specification    X11, Release 6.4


=>
     input-devices: LISTofDEVICEINFO

where

     DEVICEINFO:     [type: ATOM
              id: CARD8
              num_classes: CARD8
              use: {IsXKeyboard, IsXPointer, IsExten-
             sionDevice}
              info: LISTofINPUTINFO
              name: STRING8]

     INPUTINFO:      {KEYINFO, BUTTONINFO, VALUATORINFO}

     KEYINFO:         [class: CARD8
              length: CARD8
              min-keycode: KEYCODE
              max-keycode: KEYCODE
              num-keys: CARD16]

     BUTTONINFO:     [class: CARD8
              length: CARD8
              num-buttons: CARD16]

     VALUATORINFO:   [class: CARD8
              length: CARD8
              num_axes: CARD8
              mode: SETofDEVICEMODE
              motion_buffer_size: CARD32
              axes: LISTofAXISINFO]

     AXISINFO:         [resolution: CARD32
              min-val: CARD32
              max-val: CARD32]

     DEVICEMODE:     {Absolute, Relative}

     Errors: None

This request returns a list of all devices that can be
opened by the X server, including the core X keyboard and X
pointer.  Some implementations may open all input devices as
part of X initialization, while others may not open an input
device until requested to do so by a client program.


o  The information returned for each device is as follows:

The type field is of type Atom and indicates the nature of
the device.  Clients may determine device types by invoking
the XInternAtom request passing one of the names defined in
the header file XI.h.  The following names have been defined
to date:



                  5





X Input Extension Protocol Specification    X11, Release 6.4


     MOUSE
     TABLET
     KEYBOARD
     TOUCHSCREEN
     TOUCHPAD
     BUTTONBOX
     BARCODE
     KNOB_BOX
     TRACKBALL
     QUADRATURE
     SPACEBALL
     DATAGLOVE
     EYETRACKER
     CURSORKEYS
     FOOTMOUSE
     ID_MODULE
     ONE_KNOB
     NINE_KNOB


The id is a small cardinal value in the range 0-128 that
uniquely identifies the device.  It is assigned to the
device when it is initialized by the server.  Some implemen-
tations may not open an input device until requested by a
client program, and may close the device when the last
client accessing it requests that it be closed.  If a device
is opened by a client program via XOpenDevice, then closed
via XCloseDevice, then opened again, it is not guaranteed to
have the same id after the second open request.

The num_classes field is a small cardinal value in the range
0-255 that specifies the number of input classes supported
by the device for which information is returned by ListIn-
putDevices.  Some input classes, such as class Focus and
class Proximity do not have any information to be returned
by ListInputDevices.

The use field specifies how the device is currently being
used.  If the value is IsXKeyboard, the device is currently
being used as the X keyboard.  If the value is IsXPointer,
the device is currently being used as the X pointer.  If the
value is IsXExtensionDevice, the device is available for use
as an extension device.

The name field contains a pointer to a null-terminated
string that corresponds to one of the defined device types.

o  InputInfo is one of: KeyInfo, ButtonInfo or ValuatorInfo.
   The first two fields are common to all three:

The class field is a cardinal value in the range 0-255.  It
uniquely identifies the class of input for which information
is returned.




                  6





X Input Extension Protocol Specification    X11, Release 6.4


The length field is a cardinal value in the range 0-255.  It
specifies the number of bytes of data that are contained in
this input class.  The length includes the class and length
fields.

The remaining information returned for input class KEYCLASS
is as follows:

min_keycode is of type KEYCODE.  It specifies the minimum
keycode that the device will report.  The minimum keycode
will not be smaller than 8.

max_keycode is of type KEYCODE.  It specifies the maximum
keycode that the device will report.  The maximum keycode
will not be larger than 255.

num_keys is a cardinal value that specifies the number of
keys that the device has.

The remaining information returned for input class BUTTON-
CLASS is as follows:

num_buttons is a cardinal value that specifies the number of
buttons that the device has.

The remaining information returned for input class VALUATOR-
CLASS is as follows:

mode is a constant that has one of the following values:
Absolute or Relative.  Some devices allow the mode to be
changed dynamically via the SetDeviceMode request.

motion_buffer_size is a cardinal number that specifies the
number of elements that can be contained in the motion his-
tory buffer for the device.

The axes field contains a pointer to an AXISINFO struture.

o  The information returned for each axis reported by the
   device is:

The resolution is a cardinal value in counts/meter.

The min_val field is a cardinal value in that contains the
minimum value the device reports for this axis.  For devices
whose mode is Relative, the min_val field will contain 0.

The max_val field is a cardinal value in that contains the
maximum value the device reports for this axis.  For devices
whose mode is Relative, the max_val field will contain 0.







                  7





X Input Extension Protocol Specification    X11, Release 6.4


2.3.  Enabling Devices

Client programs that wish to access an extension device must
request that the server open that device.  This is done via
the OpenDevice request.

OpenDevice
     id: CARD8
=>

     DEVICE:           [device_id: XID
            num_classes: INT32
            classes: LISTofINPUTCLASSINFO]

     INPUTCLASSINFO:   [input_class: CARD8
            event_type_base: CARD8]


     Errors: Device


This request returns the event classes to be used by the
client to indicate which events the client program wishes to
receive.  Each input class may report several event classes.
For example, input class Keys reports DeviceKeyPress and
DeviceKeyRelease event classes.  Input classes are unique
numbers registered with the X Consortium.  Input class Other
exists to report event classes that are not specific to any
one input class, such as DeviceMappingNotify, ChangeDevi-
ceNotify, and DeviceStateNotify.


o  The information returned for each device is as follows:

The device_id is a number that uniquely identifies the
device.

The num_classes field contains the number of input classes
supported by this device.


o  For each class of input supported by the device, the
   InputClassInfo structure contains the following informa-
   tion:

The input_class is a small cardinal number that identifies
the class of input.

The event_type_base is a small cardinal number that speci-
fies the event type of one of the events reported by this
input class.  This information is not directly used by
client programs.  Instead, the Device is used by macros that
return extension event types and event classes.  This is
described in the section of this document entitled



                  8





X Input Extension Protocol Specification    X11, Release 6.4


"Selecting Extension Device Events".

Before it exits, the client program should explicitly
request that the server close the device.  This is done via
the CloseDevice request.

A client may open the same extension device more than once.
Requests after the first successful one return an additional
XDevice structure with the same information as the first,
but otherwise have no effect.  A single CloseDevice request
will terminate that client's access to the device.

Closing a device releases any active or passive grabs the
requesting client has established.  If the device is frozen
only by an active grab of the requesting client, the queued
events are released when the client terminates.

If a client program terminates without closing a device, the
server will automatically close that device on behalf of the
client.  This does not affect any other clients that may be
accessing that device.


CloseDevice
     device: DEVICE

     Errors: Device


2.4.  Changing The Mode Of A Device

Some devices are capable of reporting either relative or
absolute motion data.  To change the mode of a device from
relative to absolute, use the SetDeviceMode request.  The
valid values are Absolute or Relative.

This request will fail and return DeviceBusy if another
client already has the device open with a different mode.
It will fail and return AlreadyGrabbed if another client has
the device grabbed.  The request will fail with a BadMatch
error if the requested mode is not supported by the device.

SetDeviceMode
     device: DEVICE
     mode: {Absolute, Relative}

     Errors: Device, Match, Mode

=>
     status: {Success, DeviceBusy, AlreadyGrabbed}







                  9





X Input Extension Protocol Specification    X11, Release 6.4


2.5.  Initializing Valuators on an Input Device

Some devices that report absolute positional data can be
initialized to a starting value.  Devices that are capable
of reporting relative motion or absolute positional data may
require that their valuators be initialized to a starting
value after the mode of the device is changed to Absolute.
To initialize the valuators on such a device, use the SetDe-
viceValuators request.

SetDeviceValuators
     device: DEVICE
     first_valuator: CARD8
     num_valuators: CARD8
     valuators: LISTOFINT32

     Errors: Length, Device, Match, Value

=>
     status: {Success, AlreadyGrabbed}


This request initializes the specified valuators on the
specified extension input device.  Valuators are numbered
beginning with zero.  Only the valuators in the range speci-
fied by first_valuator and num_valuators are set.  If the
number of valuators supported by the device is less than the
expression first_valuator + num_valuators, a Value error
will result.

If the request succeeds, Success is returned.  If the
specifed device is grabbed by some other client, the request
will fail and a status of AlreadyGrabbed will be returned.

2.6.  Getting Input Device Controls


GetDeviceControl
     device: DEVICE
     control: XID

     Errors: Length, Device, Match, Value

=>
     controlState: {DeviceState}


where

     DeviceState:   DeviceResolutionState


Errors: Length, Device, Match, Value




                 10





X Input Extension Protocol Specification    X11, Release 6.4


This request returns the current state of the specified
device control.  The device control must be supported by the
target server and device or an error will result.

If the request is successful, a pointer to a generic
DeviceState structure will be returned.  The information
returned varies according to the specified control and is
mapped by a structure appropriate for that control.

GetDeviceControl will fail with a BadValue error if the
server does not support the specified control.    It will fail
with a BadMatch error if the device does not support the
specified control.

Supported device controls and the information returned for
them include:


DEVICE_RESOLUTION:   [control: CARD16
              length: CARD16
              num_valuators: CARD8
              resolutions: LISTofCARD32
              min_resolutions: LISTofCARD32
              max_resolutions: LISTofCARD32]


This device control returns a list of valuators and the
range of valid resolutions allowed for each.  Valuators are
numbered beginning with 0.  Resolutions for all valuators on
the device are returned.  For each valuator i on the device,
resolutions[i] returns the current setting of the resolu-
tion, min_resolutions[i] returns the minimum valid setting,
and max_resolutions[i] returns the maximum valid setting.

When this control is specified, XGetDeviceControl will fail
with a BadMatch error if the specified device has no valua-
tors.

ChangeDeviceControl
     device: DEVICE
     XID: controlId
     control: DeviceControl


where

     DeviceControl:   DeviceResolutionControl


Errors: Length, Device, Match, Value
=>
     status: {Success, DeviceBusy, AlreadyGrabbed}





                 11





X Input Extension Protocol Specification    X11, Release 6.4


ChangeDeviceControl changes the specifed device control
according to the values specified in the DeviceControl
structure.  The device control must be supported by the tar-
get server and device or an error will result.

The information passed with this request varies according to
the specified control and is mapped by a structure appropri-
ate for that control.

ChangeDeviceControl will fail with a BadValue error if the
server does not support the specified control.    It will fail
with a BadMatch error if the server supports the specified
control, but the requested device does not.  The request
will fail and return a status of DeviceBusy if another
client already has the device open with a device control
state that conflicts with the one specified in the request.
It will fail with a status of AlreadyGrabbed if some other
client has grabbed the specified device.  If the request
succeeds, Success is returned.    If it fails, the device con-
trol is left unchanged.

Supported device controls and the information specified for
them include:


DEVICE_RESOLUTION:   [control: CARD16
              length: CARD16
              first_valuator: CARD8
              num_valuators: CARD8
              resolutions: LISTofCARD32]


This device control changes the resolution of the specified
valuators on the specified extension input device.  Valua-
tors are numbered beginning with zero.    Only the valuators
in the range specified by first_valuator and num_valuators
are set.  A value of -1 in the resolutions list indicates
that the resolution for this valuator is not to be changed.
num_valuators specifies the number of valuators in the reso-
lutions list.

When this control is specified, XChangeDeviceControl will
fail with a BadMatch error if the specified device has no
valuators.  If a resolution is specified that is not within
the range of valid values (as returned by XGetDeviceControl)
the request will fail with a BadValue error.  If the number
of valuators supported by the device is less than the
expression first_valuator + num_valuators, a BadValue error
will result.

If the request fails for any reason, none of the valuator
resolutions will be changed.





                 12





X Input Extension Protocol Specification    X11, Release 6.4


2.7.  Selecting Extension Device Events

Extension input events are selected using the SelectExten-
sionEvent request.

SelectExtensionEvent
     window: WINDOW
     interest: LISTofEVENTCLASS

     Errors: Window, Class, Access


This request specifies to the server the events within the
specified window which are of interest to the client.  As
with the core XSelectInput function, multiple clients can
select input on the same window.

XSelectExtensionEvent requires a list of event classes.  An
event class is a 32-bit number that combines an event type
and device id, and is used to indicate which event a client
wishes to receive and from which device it wishes to receive
it.  Macros are provided to obtain event classes from the
data returned by the XOpenDevice request.  The names of
these macros correspond to the desired events, i.e. the
DeviceKeyPress is used to obtain the event class for
DeviceKeyPress events.    The syntax of the macro invocation
is:

DeviceKeyPress (device, event_type, event_class);
     device: DEVICE
     event_type: INT
     event_class: INT

The value returned in event_type is the value that will be
contained in the event type field of the XDeviceKeyPressEv-
ent when it is received by the client.    The value returned
in event_class is the value that should be passed in making
an XSelectExtensionEvent request to receive DeviceKeyPress
events.

For DeviceButtonPress events, the client may specify whether
or not an implicit passive grab should be done when the but-
ton is pressed.  If the client wants to guarantee that it
will receive a DeviceButtonRelease event for each DeviceBut-
tonPress event it receives, it should specify the DeviceBut-
tonPressGrab event class as well as the DeviceButtonPress
event class.  This restricts the client in that only one
client at a time may request DeviceButtonPress events from
the same device and window if any client specifies this
class.

If any client has specified the DeviceButtonPressGrab class,
any requests by any other client that specify the same
device and window and specify DeviceButtonPress or



                 13





X Input Extension Protocol Specification    X11, Release 6.4


DeviceButtonPressGrab will cause an Access error to be gen-
erated.

If only the DeviceButtonPress class is specified, no
implicit passive grab will be done when a button is pressed
on the device.    Multiple clients may use this class to spec-
ify the same device and window combination.

A client may also specify the DeviceOwnerGrabButton class.
If it has specified both the DeviceButtonPressGrab and the
DeviceOwnerGrabButton classes, implicit passive grabs will
activate with owner_events set to True.  If only the Device-
ButtonPressGrab class is specified, implicit passive grabs
will activate with owner_events set to False.

The client may select DeviceMotion events only when a button
is down.  It does this by specifying the event classes But-
ton1Motion through Button5Motion, or ButtonMotion.  An input
device will only support as many button motion classes as it
has buttons.

2.8.  Determining Selected Events

To determine which extension events are currently selected
from a given window, use GetSelectedExtensionEvents.

GetSelectedExtensionEvents
     window: WINDOW
=>
     this-client: LISTofEVENTCLASS
     all-clients: LISTofEVENTCLASS

     Errors: Window


This request returns two lists specifying the events
selected on the specified window.  One list gives the exten-
sion events selected by this client from the specified win-
dow.  The other list gives the extension events selected by
all clients from the specified window.    This information is
equivalent to that returned by your-event-mask and all-
event-masks in a GetWindowAttributes request.

2.9.  Controlling Event Propagation

Extension events propagate up the window hierarchy in the
same manner as core events.  If a window is not interested
in an extension event, it usually propagates to the closest
ancestor that is interested, unless the dont_propagate list
prohibits it.  Grabs of extension devices may alter the set
of windows that receive a particular extension event.

Client programs may control extension event propagation
through the use of the following two requests.



                 14





X Input Extension Protocol Specification    X11, Release 6.4


XChangeDeviceDontPropagateList adds an event to or deletes
an event from the do_not_propagate list of extension events
for the specified window.  This list is maintained for the
life of the window, and is not altered if the client termi-
nates.


ChangeDeviceDontPropagateList
     window: WINDOW
     eventclass: LISTofEVENTCLASS
     mode: {AddToList, DeleteFromList}

     Errors: Window, Class, Mode


This function modifies the list specifying the events that
are not propagated to the ancestors of the specified window.
You may use the modes AddToList or DeleteFromList.

GetDeviceDontPropagateList
     window: WINDOW

     Errors: Window
=>
     dont-propagate-list: LISTofEVENTCLASS



This function returns a list specifying the events that are
not propagated to the ancestors of the specified window.

2.10.  Sending Extension Events

One client program may send an event to another via the
XSendExtensionEvent function.

The event in the XEvent structure must be one of the events
defined by the input extension, so that the X server can
correctly byte swap the contents as necessary.    The contents
of the event are otherwise unaltered and unchecked by the X
server except to force send_event to True in the forwarded
event and to set the sequence number in the event correctly.

XSendExtensionEvent returns zero if the conversion-to-wire
protocol failed, otherwise it returns nonzero.

SendExtensionEvent
     device: DEVICE
     destination: WINDOW
     propagate: BOOL
     eventclass: LISTofEVENTCLASS
     event: XEVENT

Errors: Device, Value, Class, Window



                 15





X Input Extension Protocol Specification    X11, Release 6.4


2.11.  Getting Motion History


GetDeviceMotionEvents
     device: DEVICE
     start, stop: TIMESTAMP or CurrentTime
=>
     nevents_return: CARD32
     mode_return: {Absolute, Relative}
     axis_count_return: CARD8
     events: LISTofDEVICETIMECOORD

where

     DEVICETIMECOORD:    [data:LISTofINT32  time:TIMESTAMP]


     Errors: Device, Match


This request returns all positions in the device's motion
history buffer that fall between the specified start and
stop times inclusive.  If the start time is in the future,
or is later than the stop time, no positions are returned.

The data field of the DEVICETIMECOORD structure is a
sequence of data items.  Each item is of type INT32, and
there is one data item per axis of motion reported by the
device.  The number of axes reported by the device is
returned in the axis_count variable.

The value of the data items depends on the mode of the
device, which is returned in the mode variable.  If the mode
is Absolute, the data items are the raw values generated by
the device.  These may be scaled by the client program using
the maximum values that the device can generate for each
axis of motion that it reports.  The maximum and minimum
values for each axis are reported by the ListInputDevices
request.

If the mode is Relative, the data items are the relative
values generated by the device.  The client program must
choose an initial position for the device and maintain a
current position by accumulating these relative values.

2.12.  Changing The Core Devices

These requests are provided to change which physical device
is used as the X pointer or X keyboard.








                 16





X Input Extension Protocol Specification    X11, Release 6.4


                Note

     Using these requests may change the characteris-
     tics of the core devices.    The new pointer device
     may have a different number of buttons than the
     old one did, or the new keyboard device may have a
     different number of keys or report a different
     range of keycodes.  Client programs may be running
     that depend on those characteristics.  For exam-
     ple, a client program could allocate an array
     based on the number of buttons on the pointer
     device, and then use the button numbers received
     in button events as indicies into that array.
     Changing the core devices could cause such client
     programs to behave improperly or abnormally termi-
     nate.


These requests change the X keyboard or X pointer device and
generate an ChangeDeviceNotify event and a MappingNotify
event.    The ChangeDeviceNotify event is sent only to those
clients that have expressed an interest in receiving that
event via the XSelectExtensionEvent request.  The specified
device becomes the new X keyboard or X pointer device.    The
location of the core device does not change as a result of
this request.

These requests fail and return AlreadyGrabbed if either the
specified device or the core device it would replace are
grabbed by some other client.  They fail and return
GrabFrozen if either device is frozen by the active grab of
another client.

These requests fail with a BadDevice error if the specified
device is invalid, or has not previously been opened via
OpenDevice.


To change the X keyboard device, use the ChangeKeyboardDe-
vice request.  The specified device must support input class
Keys (as reported in the ListInputDevices request) or the
request will fail with a BadMatch error.  Once the device
has successfully replaced one of the core devices, it is
treated as a core device until it is in turn replaced by
another ChangeDevice request, or until the server termi-
nates.    The termination of the client that changed  the
device will not cause it to change back.  Attempts to use
the CloseDevice request to close the new core device will
fail with a BadDevice error.

The focus state of the new keyboard is the same as the focus
state of the old X keyboard.  If the new keyboard was not
initialized with a FocusRec, one is added by the ChangeKey-
boardDevice request.  The X keyboard is assumed to have a



                 17





X Input Extension Protocol Specification    X11, Release 6.4


KbdFeedbackClassRec.  If the device was initialized without
a KbdFeedbackClassRec, one will be added by this request.
The KbdFeedbackClassRec will specify a null routine as the
control procedure and the bell procedure.

ChangeKeyboardDevice
     device: DEVICE

     Errors: Device, Match
=>
     status: Success, AlreadyGrabbed, Frozen


To change the X pointer device, use the ChangePointerDevice
request.  The specified device must support input class Val-
uators (as reported in the ListInputDevices request) or the
request will fail with a BadMatch error.  The valuators to
be used as the x- and y-axes of the pointer device must be
specified.  Data from other valuators on the device will be
ignored.

The X pointer device does not contain a FocusRec.  If the
new pointer was initialized with a FocusRec, it is freed by
the ChangePointerDevice request.  The X pointer is assumed
to have a ButtonClassRec and a PtrFeedbackClassRec.  If the
device was initialized without a ButtonClassRec or a Ptr-
FeedbackClassRec, one will be added by this request.  The
ButtonClassRec added will have no buttons, and the PtrFeed-
backClassRec will specify a null routine as the control pro-
cedure.

If the specified device reports absolute positional informa-
tion, and the server implementation does not allow such a
device to be used as the X pointer, the request will fail
with a BadDevice error.

Once the device has successfully replaced one of the core
devices, it is treated as a core device until it is in turn
replaced by another ChangeDevice request, or until the
server terminates.  The termination of the client that
changed  the device will not cause it to change back.
Attempts to use the CloseDevice request to close the new
core device will fail with a BadDevice error.

ChangePointerDevice
     device: DEVICE
     xaxis: CARD8
     yaxis: CARD8

     Errors: Device, Match
=>
     status: Success, AlreadyGrabbed, Frozen





                 18





X Input Extension Protocol Specification    X11, Release 6.4


2.13.  Event Synchronization And Core Grabs

Implementation of the input extension requires an extension
of the meaning of event synchronization for the core grab
requests.  This is necessary in order to allow window man-
agers to freeze all input devices with a single request.

The core grab requests require a pointer_mode and key-
board_mode argument.  The meaning of these modes is changed
by the input extension.  For the XGrabPointer and XGrabBut-
ton requests, pointer_mode controls synchronization of the
pointer device, and keyboard_mode controls the synchroniza-
tion of all other input devices.  For the XGrabKeyboard and
XGrabKey requests, pointer_mode controls the synchronization
of all input devices except the X keyboard, while key-
board_mode controls the synchronization of the keyboard.
When using one of the core grab requests, the synchroniza-
tion of extension devices is controlled by the mode speci-
fied for the device not being grabbed.

2.14.  Extension Active Grabs

Active grabs of extension devices are supported via the
GrabDevice request in the same way that core devices are
grabbed using the core GrabKeyboard request, except that a
Device is passed as a function parameter.  A list of events
that the client wishes to receive is also passed.  The
UngrabDevice request allows a previous active grab for an
extension device to be released.

To grab an extension device, use the GrabDevice request.
The device must have previously been opened using the Open-
Device request.

GrabDevice
     device: DEVICE
     grab-window: WINDOW
     owner-events: BOOL
     event-list: LISTofEVENTCLASS
     this-device-mode: {Synchronous, Asynchronous}
     other-device-mode: {Synchronous, Asynchronous}
     time:TIMESTAMP or CurrentTime
=>
     status: Success, AlreadyGrabbed, Frozen, InvalidTime,
     NotViewable

     Errors:  Device, Window, Value


This request actively grabs control of the specified input
device.  Further input events from this device are reported
only to the grabbing client.  This request overrides any
previous active grab by this client for this device.




                 19





X Input Extension Protocol Specification    X11, Release 6.4


The event-list parameter is a pointer to a list of event
classes.  These are used to indicate which events the client
wishes to receive while the device is grabbed.    Only event
classes obtained from the grabbed device are valid.

If owner-events is False, input events generated from this
device are reported with respect to grab-window, and are
only reported if selected by being included in the event-
list.  If owner-events is True, then if a generated event
would normally be reported to this client, it is reported
normally, otherwise the event is reported with respect to
the grab-window, and is only reported if selected by being
included in the event-list.  For either value of owner-
events, unreported events are discarded.

If this-device-mode is Asynchronous, device event processing
continues normally.  If the device is currently frozen by
this client, then processing of device events is resumed.
If this-device-mode is Synchronous, the state of the grabbed
device (as seen by means of the protocol) appears to freeze,
and no further device events are generated by the server
until the grabbing client issues a releasing AllowDe-
viceEvents request or until the device grab is released.
Actual device input events are not lost while the device is
frozen; they are simply queued for later processing.

If other-device-mode is Asynchronous, event processing is
unaffected by activation of the grab.  If other-device-mode
is Synchronous, the state of all input devices except the
grabbed one (as seen by means of the protocol) appears to
freeze, and no further events are generated by the server
until the grabbing client issues a releasing AllowDe-
viceEvents request or until the device grab is released.
Actual events are not lost while the devices are frozen;
they are simply queued for later processing.

This request generates DeviceFocusIn and DeviceFocusOut
events.

This request fails and returns:

o  AlreadyGrabbed If the device is actively grabbed by some
   other client.

o  NotViewable If grab-window is not viewable.

o  InvalidTime If the specified time is earlier than the
   last-grab-time for the specified device or later than the
   current X server time. Otherwise, the last-grab-time for
   the specified device is set to the specified time and
   CurrentTime is replaced by the current X server time.

o  Frozen If the device is frozen by an active grab of
   another client.



                 20





X Input Extension Protocol Specification    X11, Release 6.4


If a grabbed device is closed by a client while an active
grab by that client is in effect, that active grab will be
released.  Any passive grabs established by that client will
be released.  If the device is frozen only by an active grab
of the requesting client, it is thawed.

To release a grab of an extension device, use UngrabDevice.

UngrabDevice
     device: DEVICE
     time: TIMESTAMP or CurrentTime

     Errors:  Device


This request releases the device if this client has it
actively grabbed (from either GrabDevice or GrabDeviceKey)
and releases any queued events.  If any devices were frozen
by the grab, UngrabDevice thaws them.  The request has no
effect if the specified time is earlier than the last-
device-grab time or is later than the current server time.

This request generates DeviceFocusIn and DeviceFocusOut
events.

An UngrabDevice is performed automatically if the event win-
dow for an active device grab becomes not viewable.

2.15.  Passively Grabbing A Key

Passive grabs of buttons and keys on extension devices are
supported via the GrabDeviceButton and GrabDeviceKey
requests.  These passive grabs are released via the Ungrab-
DeviceKey and UngrabDeviceButton requests.

To passively grab a single key on an extension device, use
GrabDeviceKey.    That device must have previously been opened
using the OpenDevice request.

GrabDeviceKey

     device: DEVICE
     keycode: KEYCODE or AnyKey
     modifiers: SETofKEYMASK or AnyModifier
     modifier-device: DEVICE or NULL
     grab-window: WINDOW
     owner-events: BOOL
     event-list: LISTofEVENTCLASS
     this-device-mode: {Synchronous, Asynchronous}
     other-device-mode: {Synchronous, Asynchronous}

     Errors:  Device, Match, Access, Window, Value





                 21





X Input Extension Protocol Specification    X11, Release 6.4


This request is analogous to the core GrabKey request.    It
establishes a passive grab on a device.  Consequently, In
the future:

o  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),

o  AND no other modifier keys logically are down,

o  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,

o  AND a passive grab on the same device and key combination
   does not exist on any ancestor of the grab window,

o  THEN the device is actively grabbed, as for GrabDevice,
   the last-device-grab time is set to the time at which the
   key was pressed (as transmitted in the DeviceKeyPress
   event), and the DeviceKeyPress event is reported.

The interpretation of the remaining arguments is as for
GrabDevice.  The active grab is terminated automatically
when logical state of the device has the specified key
released (independent of the logical state of the modifier
keys).

Note that the logical state of a device (as seen by means of
the X protocol) may lag the physical state if device event
processing is frozen.

A modifier of AnyModifier is equivalent to issuing the
request for all possible modifier combinations (including
the combination of no modifiers).  It is not required that
all modifiers specified have currently assigned keycodes.  A
key of AnyKey is equivalent to issuing the request for all
possible keycodes.  Otherwise, the key must be in the range
specified by min-keycode and max-keycode in the ListInputDe-
vices request.    If it is not within that range, GrabDe-
viceKey generates a Value error.

NULL may be passed for the modifier_device.  If the modi-
fier_device is NULL, the core X keyboard is used as the mod-
ifier_device.

An Access error is generated if some other client has issued
a GrabDeviceKey with the same device and key combination on
the same window.  When using AnyModifier or AnyKey, the
request fails completely and the X server generates a Access
error and no grabs are established if there is a conflicting
grab for any combination.




                 22





X Input Extension Protocol Specification    X11, Release 6.4


This request cannot be used to grab a key on the X keyboard
device.  The core GrabKey request should be used for that
purpose.

To release a passive grab of a single key on an extension
device, use UngrabDeviceKey.

UngrabDeviceKey

     device: DEVICE
     keycode: KEYCODE or AnyKey
     modifiers: SETofKEYMASK or AnyModifier
     modifier-device: DEVICE or NULL
     grab-window: WINDOW

     Errors:  Device, Match, Window, Value, Alloc


This request is analogous to the core UngrabKey request.  It
releases the key combination on the specified window if it
was grabbed by this client.  A modifier of AnyModifier is
equivalent to issuing the request for all possible modifier
combinations (including the combination of no modifiers).  A
key of AnyKey is equivalent to issuing the request for all
possible keycodes.  This request has no effect on an active
grab.

NULL may be passed for the modifier_device.  If the modi-
fier_device is NULL, the core X keyboard is used as the mod-
ifier_device.

2.16.  Passively Grabbing A Button

To establish a passive grab for a single button on an exten-
sion device, use GrabDeviceButton.

GrabDeviceButton

     device: DEVICE
     button: BUTTON or AnyButton
     modifiers: SETofKEYMASK or AnyModifier
     modifier-device: DEVICE or NULL
     grab-window: WINDOW
     owner-events: BOOL
     event-list: LISTofEVENTCLASS
     this-device-mode: {Synchronous, Asynchronous}
     other-device-mode: {Synchronous, Asynchronous}

     Errors:  Device, Match, Window, Access, Value


This request is analogous to the core GrabButton request.
It establishes an explicit passive grab for a button on an
extension input device.  Since the server does not track



                 23





X Input Extension Protocol Specification    X11, Release 6.4


extension devices, no cursor is specified with this request.
For the same reason, there is no confine-to parameter.    The
device must have previously been opened using the OpenDevice
request.

The GrabDeviceButton request establishes a passive grab on a
device.  Consequently, in the future,

o  IF the device is not grabbed and the specified button is
   logically pressed when the specified modifier keys logi-
   cally are down (and no other buttons or modifier keys are
   down),

o  AND the grab window contains the device,

o  AND a passive grab on the same device and button/ key
   combination does not exist on any ancestor of the grab
   window,

o  THEN the device is actively grabbed, as for GrabDevice,
   the last-grab time is set to the time at which the button
   was pressed (as transmitted in the DeviceButtonPress
   event), and the DeviceButtonPress event is reported.

The interpretation of the remaining arguments is as for
GrabDevice.  The active grab is terminated automatically
when logical state of the device has all buttons released
(independent of the logical state of the modifier keys).

Note that the logical state of a device (as seen by means of
the X protocol) may lag the physical state if device event
processing is frozen.

A modifier of AnyModifier is equivalent to issuing the
request for all possible modifier combinations (including
the combination of no modifiers).  It is not required that
all modifiers specified have currently assigned keycodes.  A
button of AnyButton is equivalent to issuing the request for
all possible buttons.  It is not required that the specified
button be assigned to a physical button.

NULL may be passed for the modifier_device.  If the modi-
fier_device is NULL, the core X keyboard is used as the mod-
ifier_device.

An Access error is generated if some other client has issued
a GrabDeviceButton with the same device and button combina-
tion on the same window.  When using AnyModifier or AnyBut-
ton, the request fails completely and the X server generates
a Access error and no grabs are established if there is a
conflicting grab for any combination.  The request has no
effect on an active grab.





                 24





X Input Extension Protocol Specification    X11, Release 6.4


This request cannot be used to grab a button on the X
pointer device.  The core GrabButton request should be used
for that purpose.

To release a passive grab of a button on an extension
device, use UngrabDeviceButton.

UngrabDeviceButton

     device: DEVICE
     button: BUTTON or AnyButton
     modifiers: SETofKEYMASK or AnyModifier
     modifier-device: DEVICE or NULL
     grab-window: WINDOW

     Errors:  Device, Match, Window, Value, Alloc


This request is analogous to the core UngrabButton request.
It releases the passive button/key combination on the speci-
fied window if it was grabbed by the client.  A modifiers of
AnyModifier is equivalent to issuing the request for all
possible modifier combinations (including the combination of
no modifiers).    A button of AnyButton is equivalent to issu-
ing the request for all possible buttons.  This request has
no effect on an active grab. The device must have previously
been opened using the OpenDevice request otherwise a Device
error will be generated.

NULL may be passed for the modifier_device.  If the modi-
fier_device is NULL, the core X keyboard is used as the mod-
ifier_device.

This request cannot be used to ungrab a button on the X
pointer device.  The core UngrabButton request should be
used for that purpose.

2.17.  Thawing A Device

To allow further events to be processed when a device has
been frozen, use AllowDeviceEvents.

AllowDeviceEvents
     device: DEVICE
     event-mode: {AsyncThisDevice, SyncThisDevice, Asyn-
     cOtherDevices, ReplayThisdevice, AsyncAll, or SyncAll}
     time:TIMESTAMP or CurrentTime

     Errors:  Device, Value


The AllowDeviceEvents request releases some queued events if
the client has caused a device to freeze.  The request has
no effect if the specified time is earlier than the last-



                 25





X Input Extension Protocol Specification    X11, Release 6.4


grab time of the most recent active grab for the client, or
if the specified time is later than the current X server
time.

The following describes the processing that occurs depending
on what constant you pass to the event-mode argument:

o  If the specified device is frozen by the client, event
   processing for that device continues as usual.  If the
   device is frozen multiple times  by the client on behalf
   of multiple separate grabs, AsyncThisDevice thaws for
   all.  AsyncThisDevice has no effect if the specified
   device is not frozen by the client, but the device need
   not be grabbed by the client.

o  If the specified device is frozen and actively grabbed by
   the client, event processing for that device continues
   normally until the next button or key event is reported
   to the client.  At this time, the specified device again
   appears to freeze.  However, if the reported event causes
   the grab to be released, the specified device does not
   freeze.  SyncThisDevice has no effect if the specified
   device is not frozen by the client or is not grabbed by
   the client.

o  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 GrabDe-
   viceButton or from a previous AllowDeviceEvents with mode
   SyncThisDevice, but not from a Grab), the grab is
   released and that event is completely reprocessed.  This
   time, however, the request ignores any passive grabs at
   or above (towards the root) the grab-window of the grab
   just released.  The request has no effect if the speci-
   fied device is not grabbed by the client or if it is not
   frozen as the result of an event.

o  If the remaining devices are frozen by the client, event
   processing for them continues as usual.  If the other
   devices are frozen multiple times  by the client on
   behalf of multiple separate grabs, AsyncOtherDevices
   ``thaws'' for all.  AsyncOtherDevices has no effect if
   the devices are not frozen by the client, but those
   devices need not be grabbed by the client.

o  If all devices are frozen by the client, event processing
   (for all devices) continues normally until the next but-
   ton or key event is reported to the client for a grabbed
   device (button event for the grabbed device, key or
   motion event for the device), at which time the devices
   again appear to freeze.  However, if the reported event
   causes the grab to be released, then the devices do not
   freeze (but if any device is still grabbed, then a subse-
   quent event for it will still cause all devices to



                 26





X Input Extension Protocol Specification    X11, Release 6.4


   freeze).  SyncAll has no effect unless all devices are
   frozen by the client.  If any device is frozen twice by
   the client on behalf of two separate grabs, SyncAll
   "thaws" for both (but a subsequent freeze for SyncAll
   will only freeze each device once).

o  If all devices are frozen by the client, event processing
   (for all devices) continues normally.  If any device is
   frozen multiple times by the client on behalf of multiple
   separate grabs, AsyncAll "thaws" for all.  AsyncAll has
   no effect unless all devices are frozen by the client.

AsyncThisDevice, SyncThisDevice, and ReplayThisDevice have
no effect on the processing of events from the remaining
devices.  AsyncOtherDevices has no effect on the processing
of events from the specified device.  When the event_mode is
SyncAll or AsyncAll, the device parameter is ignored.

It is possible for several grabs of different devices (by
the same or different clients) to be active simultaneously.
If a device is frozen on behalf of any grab, no event pro-
cessing is performed for the device.  It is possible for a
single device to be frozen because of several grabs.  In
this case, the freeze must be released on behalf of each
grab before events can again be processed.


2.18.  Controlling Device Focus

The current focus window for an extension input device can
be determined using the GetDeviceFocus request.  Extension
devices are focused using the SetDeviceFocus request in the
same way that the keyboard is focused using the SetInputFo-
cus request, except that a device is specified as part of
the request. One additional focus state, FollowKeyboard, is
provided for extension devices.

To get the current focus state, revert state, and focus time
of an extension device, use GetDeviceFocus.

GetDeviceFocus

     device: DEVICE
=>
     focus: WINDOW, PointerRoot, FollowKeyboard, or None
     revert-to: Parent, PointerRoot, FollowKeyboard, or None
     focus-time: TIMESTAMP

     Errors:  Device, Match


This request returns the current focus state, revert-to
state, and last-focus-time of an extension device.




                 27





X Input Extension Protocol Specification    X11, Release 6.4


To set the focus of an extension device, use SetDeviceFocus.

SetDeviceFocus
     device: DEVICE
     focus: WINDOW, PointerRoot, FollowKeyboard, or None
     revert-to: Parent, PointerRoot, FollowKeyboard, or None
     focus-time: TIMESTAMP

     Errors:  Device, Window, Value, Match


This request changes the focus for an extension input device
and the last-focus-change-time.  The request has no effect
if the specified time is earlier than the last-focus-change-
time or is later than the current X server time.  Otherwise,
the last-focus-change-time is set to the specified time,
with CurrentTime replaced by the current server time.

The action taken by the server when this request is
requested depends on the value of the focus argument:

o  If the focus argument is None, 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.

o  If a window ID is assigned to the focus argument, it
   becomes the focus window of the device.  If an input
   event from the device would normally be reported to this
   window or to one of its inferiors, the event is reported
   normally.  Otherwise, the event is reported relative to
   the focus window.

o  If you assign PointerRoot to the focus argument, the
   focus window is dynamically taken to be the root window
   of whatever screen the pointer is on at each input event.
   In this case, the revert-to argument is ignored.

o  If you assign FollowKeyboard to the focus argument, the
   focus window is dynamically taken to be the same as the
   focus of the X keyboard at each input event.

The specified focus window must be viewable at the time of
the request (else a Match error).  If the focus window later
becomes not viewable, the X server evaluates the revert-to
argument to determine the new focus window.

o  If you assign RevertToParent to the revert-to argument,
   the focus reverts to the parent (or the closest viewable
   ancestor), and the new revert-to value is taken to be
   RevertToNone.

o  If you assign RevertToPointerRoot, RevertToFollowKey-
   board, or RevertToNone to the revert-to argument, the
   focus reverts to that value.



                 28





X Input Extension Protocol Specification    X11, Release 6.4


When the focus reverts, the X server generates DeviceFocusIn
and DeviceFocusOut events, but the last-focus-change time is
not affected.

This request causes the X server to generate DeviceFocusIn
and DeviceFocusOut events.

2.19.  Controlling Device Feedback

To get the settings of feedbacks on an extension device, use
GetFeedbackControl.   This request provides functionality
equivalent to the core GetKeyboardControl and GetPointerCon-
trol functions.  It also provides a way to control displays
associated with an input device that are capable of display-
ing an integer or string.

GetFeedbackControl
     device: DEVICE
=>
     num_feedbacks_return: CARD16
     return_value: LISTofFEEDBACKSTATE

     where

      FEEDBACKSTATE:   {KbdFeedbackState, PtrFeedbackState,
               IntegerFeedbackState, StringFeedback-
               State, BellFeedbackState, LedFeedback-
               State}


Feedbacks are reported by class.  Those feedbacks that are
reported for the core keyboard device are in class KbdFeed-
back, and are returned in the KbdFeedbackState structure.
The members of that structure are as follows:

     CLASS Kbd:   [class: CARD8
           length: CARD16
           feedback id: CARD8
           key_click_percent: CARD8
           bell_percent: CARD8
           bell_pitch: CARD16
           bell_duration: CARD16
           led_value: BITMASK
           global_auto_repeat: {AutoRepeatModeOn,
          AutoRepeatModeOff}
           auto_repeats: LISTofCARD8]


Those feedbacks that are equivalent to those reported for
the core pointer are in feedback class PtrFeedback and are
reported in the PtrFeedbackState structure.  The members of
that structure are:





                 29





X Input Extension Protocol Specification    X11, Release 6.4


     CLASS Ptr:   [class: CARD8
           length: CARD16
           feedback id: CARD8
           accelNumerator: CARD16
           accelDenominator: CARD16
           threshold: CARD16]


Some input devices provide a means of displaying an integer.
Those devices will support feedback class IntegerFeedback,
which is reported in the IntegerFeedbackState structure.
The members of that structure are:



     CLASS Integer:   [class: CARD8
               length: CARD16
               feedback id: CARD8
               resolution: CARD32
               min-val: INT32
               max-val: INT32]


Some input devices provide a means of displaying a string.
Those devices will support feedback class StringFeedback,
which is reported in the StringFeedbackState structure.  The
members of that structure are:


     CLASS String:   [class: CARD8
              length: CARD16
              feedback id: CARD8
              max_symbols: CARD16
              num_keysyms_supported: CARD16
              keysyms_supported: LISTofKEYSYM]


Some input devices contain a bell.  Those devices will sup-
port feedback class BellFeedback, which is reported in the
BellFeedbackState structure.  The members of that structure
are:



     CLASS Bell:   [class: CARD8
            length: CARD16
            feedback id: CARD8
            percent: CARD8
            pitch: CARD16
            duration: CARD16]


The percent sets the base volume for the bell between 0
(off) and 100 (loud) inclusive, if possible.  Setting to -1



                 30





X Input Extension Protocol Specification    X11, Release 6.4


restores the default.  Other negative values generate a
Value error.

The pitch sets the pitch (specified in Hz) of the bell, if
possible.  Setting to -1 restores the default.    Other nega-
tive values generate a Value error.

The duration sets the duration (specified in milliseconds)
of the bell, if possible.  Setting to -1 restores the
default.  Other negative values generate a Value error.

A bell generator connected with the console but not directly
on the device is treated as if it were part of the device.
Some input devices contain LEDs.  Those devices will support
feedback class Led, which is reported in the LedFeedback-
State structure.  The members of that structure are:



     CLASS Led:   [class: CARD8
           length: CARD16
           feedback id: CARD8
           led_mask: BITMASK
           led_value: BITMASK]


Each bit in led_mask indicates that the corresponding led is
supported by the feedback.  At most 32 LEDs per feedback are
supported.  No standard interpretation of LEDs is defined.

This function will fail with a BadMatch error if the device
specified in the request does not support feedbacks.

Errors:  Device, Match

To change the settings of a feedback on an extension device,
use ChangeFeedbackControl.

ChangeFeedbackControl
     device: DEVICE
     feedbackid: CARD8
     value-mask: BITMASK
     value: FEEDBACKCONTROL

     Errors:  Device, Match, Value



FEEDBACKCONTROL:   {KBDFEEDBACKCONTROL, PTRFEEDBACKCONTROL,
           INTEGERFEEDBACKCONTROL, STRINGFEEDBACK-
           CONTROL, BELLFEEDBACKCONTROL, LEDFEED-
           BACKCONTROL}





                 31





X Input Extension Protocol Specification    X11, Release 6.4


Feedback controls are grouped by class.  Those feedbacks
that are equivalent to those supported by the core keyboard
are controlled by feedback class KbdFeedbackClass using the
KbdFeedbackControl structure.  The members of that structure
are:

     KBDFEEDBACKCTL:   [class: CARD8
            length: CARD16
            feedback id: CARD8
            key_click_percent: INT8
            bell_percent: INT8
            bell_pitch: INT16
            bell_duration: INT16
            led_mask: INT32
            led_value: INT32
            key: KEYCODE
            auto_repeat_mode: {AutoRepeatModeOn,
             AutoRepeatModeOff, AutoRepeatModeDe-
               fault}]


The key_click_percent sets the volume for key clicks between
0 (off) and 100 (loud) inclusive, if possible.    Setting to
-1 restores the default.  Other negative values generate a
Value error.

If both auto_repeat_mode and key are specified, then the
auto_repeat_mode of that key is changed, if possible.  If
only auto_repeat_mode is specified, then the global auto-
repeat mode for the entire keyboard is changed, if possible,
without affecting the per-key settings.  It is a Match error
if a key is specified without an auto_repeat_mode.

The order in which controls are verified and altered is
server-dependent.  If an error is generated, a subset of the
controls may have been altered.

Those feedback controls equivalent to those of the core
pointer are controlled by feedback class PtrFeedbackClass
using the PtrFeedbackControl structure.  The members of that
structure are as follows:


     PTRFEEDBACKCTL:   [class: CARD8
            length: CARD16
            feedback id: CARD8
            accelNumerator: INT16
            accelDenominator: INT16
            threshold: INT16]


The acceleration, expressed as a fraction, is a multiplier
for movement. For example, specifying 3/1 means the device
moves three times as fast as normal.  The fraction may be



                 32





X Input Extension Protocol Specification    X11, Release 6.4


rounded arbitrarily by the X server.  Acceleration only
takes effect if the device moves more than threshold pixels
at once and only applies to the amount beyond the value in
the threshold argument.  Setting a value to -1 restores the
default.  The values of the do-accel and do-threshold argu-
ments must be nonzero for the device values to be set.    Oth-
erwise, the parameters will be unchanged.  Negative values
generate a Value error, as does a zero value for the accel-
denominator argument.

Some devices are capable of displaying an integer.  This is
done using feedback class IntegerFeedbackClass using the
IntegerFeedbackControl structure.  The members of that
structure are as follows:


     INTEGERCTL:   [class: CARD8
            length: CARD16
            feedback id: CARD8
            int_to_display: INT32]


Some devices are capable of displaying an string.  This is
done using feedback class StringFeedbackClass using the
StringFeedbackCtl structure.  The members of that structure
are as follows:


     STRINGCTL:   [class: CARD8
           length: CARD16
           feedback id: CARD8
           syms_to_display: LISTofKEYSYMS]


Some devices contain a bell.  This is done using feedback
class BellFeedbackClass using the BellFeedbackControl struc-
ture.  The members of that structure are as follows:


     BELLCTL:    [class: CARD8
         length: CARD16
         feedback id: CARD8
         percent: INT8
         pitch: INT16
         duration: INT16]


Some devices contain leds.  These can be turned on and off
using the LedFeedbackControl structure.  The members of that
structure are as follows:







                 33





X Input Extension Protocol Specification    X11, Release 6.4


     LEDCTL:   [class: CARD8
        length: CARD16
        feedback id: CARD8
        led_mask: BITMASK
        led_value: BITMASK]


Errors:  Device, Match, Value


2.20.  Ringing a Bell on an Input Device

To ring a bell on an extension input device, use DeviceBell.

DeviceBell

     device: DEVICE
     feedbackclass: CARD8
     feedbackid: CARD8
     percent: INT8

     Errors: Device, Value


This request is analogous to the core Bell request.  It
rings the specified bell on the specified input device feed-
back, using the specified volume.  The specified volume is
relative to the base volume for the feedback.  If the value
for the percent argument is not in the range -100 to 100
inclusive, a Value error results.  The volume at which the
bell rings when the percent argument is nonnegative is:


        base - [(base * percent) / 100] + percent


The volume at which the bell rings when the percent argument
is negative is:

        base + [(base * percent) / 100]


To change the base volume of the bell, use ChangeFeedback-
Control request.


2.21.  Controlling Device Encoding

To get the keyboard mapping of an extension device that has
keys, use GetDeviceKeyMapping.

GetDeviceKeyMapping





                 34





X Input Extension Protocol Specification    X11, Release 6.4


     device: DEVICE
     first-keycode: KEYCODE
     count: CARD8
=>
     keysyms-per-keycode: CARD8
     keysyms: LISTofKEYSYM

     Errors: Device, Match, Value


This request returns the symbols for the specified number of
keycodes for the specified extension device, starting with
the specified keycode.    The first-keycode must be greater
than or equal to min-keycode as returned in the connection
setup (else a Value error), and


     first-keycode + count - 1


must be less than or equal to max-keycode as returned in the
connection setup (else a Value error).    The number of ele-
ments in the keysyms list is


     count * keysyms-per-keycode

and KEYSYM number N (counting from zero) for keycode K has
an index (counting from zero) of


     (K - first-keycode) * keysyms-per-keycode + N


in keysyms.  The keysyms-per-keycode value is chosen arbi-
trarily by the server to be large enough to report all
requested symbols.  A special KEYSYM value of NoSymbol is
used to fill in unused elements for individual keycodes.

If the specified device has not first been opened by this
client via OpenDevice, or if that device does not support
input class Keys, this request will fail with a Device
error.

To change the keyboard mapping of an extension device that
has keys, use ChangeDeviceKeyMapping.

ChangeDeviceKeyMapping
     device: DEVICE
     first-keycode: KEYCODE
     keysyms-per-keycode: CARD8
     keysyms: LISTofKEYSYM
     num_codes: CARD8




                 35





X Input Extension Protocol Specification    X11, Release 6.4


     Errors:  Device, Match, Value, Alloc


This request is analogous to the core ChangeKeyMapping
request.  It defines the symbols for the specified number of
keycodes for the specified extension device.  If the speci-
fied device has not first been opened by this client via
OpenDevice, or if that device does not support input class
Keys, this request will fail with a Device error.

The number of elements in the keysyms list must be a multi-
ple of keysyms_per_keycode.  Otherwise, ChangeDeviceKeyMap-
ping generates a Length error.    The specified first_keycode
must be greater than or equal to the min_keycode value
returned by the ListInputDevices request, or this request
will fail with a Value error.  In addition, if the following
expression is not less than the max_keycode value returned
by the ListInputDevices request, the request will fail with
a Value error:


        first_keycode + (num_codes / keysyms_per_keycode) - 1


To obtain the keycodes that are used as modifiers on an
extension device that has keys, use GetDeviceModifierMap-
ping.

GetDeviceModifierMapping
     device: DEVICE
=>
     keycodes-per-modifier: CARD8
     keycodes: LISTofKEYCODE

     Errors:  Device, Match


This request is analogous to the core GetModifierMapping
request.  This request returns the keycodes of the keys
being used as modifiers.  The number of keycodes in the list
is 8*keycodes-per-modifier.  The keycodes are divided into
eight sets, with each set containing keycodes-per-modifier
elements.  The sets are assigned in order to the modifiers
Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. The
keycodes-per-modifier value is chosen arbitrarily by the
server; zeroes are used to fill in unused elements within
each set.  If only zero values are given in a set, the use
of the corresponding modifier has been disabled.  The order
of keycodes within each set is chosen arbitrarily by the
server.

To set which keycodes that are to be used as modifiers for
an extension device, use SetDeviceModifierMapping.




                 36





X Input Extension Protocol Specification    X11, Release 6.4


SetDeviceModifierMapping

     device: DEVICE
     keycodes-per-modifier: CARD8
     keycodes: LISTofKEYCODE
=>
     status: {Success, Busy, Failed}

     Errors:  Device, Match, Value, Alloc


This request is analogous to the core SetModifierMapping
request.  This request specifies the keycodes (if any) of
the keys to be used as modifiers.  The number of keycodes in
the list must be 8*keycodes-per-modifier (else a Length
error).  The keycodes are divided into eight sets, with the
sets, with each set containing keycodes-per-modifier ele-
ments.    The sets are assigned in order to the modifiers
Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5.
Only non-zero keycode values are used within each set; zero
values are ignored.  All of the non-zero keycodes must be in
the range specified by min-keycode and max-keycode in the
ListInputDevices request (else a Value error).    The order of
keycodes within a set does not matter.    If no non-zero val-
ues are specified in a set, the use of the corresponding
modifier is disabled, and the modifier bit will always be
zero.  Otherwise, the modifier bit will be one whenever at
least one of the keys in the corresponding set is in the
down position.

A server can impose restrictions on how modifiers can be
changed (for example, if certain keys do not generate up
transitions in hardware or if multiple keys per modifier are
not supported).  The status reply is Failed if some such
restriction is violated, and none of the modifiers are
changed.

If the new non-zero keycodes specified for a modifier differ
from those currently defined, and any (current or new) keys
for that modifier are logically in the down state, then the
status reply is Busy, and none of the modifiers are changed.

     This request generates a DeviceMappingNotify event on a
     Success status.  The DeviceMappingNotify event will be
     sent only to those clients that have expressed an
     interest in receiving that event via the XSelectExten-
     sionEvent request.

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 MappingFailed , and none of the modifiers are
changed.  If the new keycodes specified for a modifier



                 37





X Input Extension Protocol Specification    X11, Release 6.4


differ from those currently defined and any (current or new)
keys for that modifier are in the logically down state, the
status reply is MappingBusy, and none of the modifiers are
changed.

2.22.  Controlling Button Mapping

These requests are analogous to the core GetPointerMapping
and ChangePointerMapping requests.  They allow a client to
determine the current mapping of buttons on an extension
device, and to change that mapping.

To get the current button mapping for an extension device,
use GetDeviceButtonMapping.

GetDeviceButtonMapping
     device: DEVICE
     nmap: CARD8
=>
     map_return: LISTofCARD8

     Errors:  Device, Match


The GetDeviceButtonMapping function returns the current map-
ping of the buttons on the specified device.  Elements of
the list are indexed starting from one.  The length of the
list indicates the number of physical buttons.    The nominal
mapping is the identity mapping map[i]=i.

nmap indicates the number of elements in the map_return
array.    Only the first nmap entries will be copied by the
library into the map_return array.



To set the button mapping for an extension device, use Set-
DeviceButtonMapping.

SetDeviceButtonMapping
     device: DEVICE
     map: LISTofCARD8
     nmap: CARD8

=>
     status: CARD8

     Errors:  Device, Match, Value


The SetDeviceButtonMapping function sets the mapping of the
specified device and causes the X server to generate a
DeviceMappingNotify event on a status of MappingSuccess.
Elements of the list are indexed starting from one.  The



                 38





X Input Extension Protocol Specification    X11, Release 6.4


length of the list, specified in nmap, must be the same as
GetDeviceButtonMapping would return.  Otherwise, SetDevice-
ButtonMapping generates a Value error.    A zero element dis-
ables a buttons, and elements are not restricted in value by
the number of physical buttons.  However, no two elements
can have the same nonzero value.  Otherwise, this function
generates a Value error.  If any of the buttons to be
altered are in the down state, the status reply is Mapping-
Busy and the mapping is not changed.

2.23.  Obtaining The State Of A Device

To obtain vectors that describe the state of the keys, but-
tons and valuators of an extension device, use QueryDeviceS-
tate.

QueryDeviceState
     device: DEVICE
=>
     device-id: CARD8
     data: LISTofINPUTCLASS

where

     INPUTCLASS:       {VALUATOR, BUTTON, KEY}

     CLASS VALUATOR:   [class: CARD8
            num_valuators: CARD8
               mode: CARD8
                #x01 device mode
                 (0 = Relative, 1 = Absolute)
                #x02 proximity state
                 (0 = InProximity, 1 = OutOf-
                 Proximity)
            valuators: LISTofINT32]

     CLASS BUTTON:     [class: CARD8
            num_buttons: CARD8
            buttons: LISTofCARD8]

     CLASS KEY:        [class: CARD8
            num_keys: CARD8
            keys: LISTofCARD8]


     Errors:  Device


The QueryDeviceState request returns the current logical
state of the buttons, keys, and valuators on the specified
input device.  The buttons and keys arrays, byte N (from 0)
contains the bits for key or button 8N to 8N+7 with the
least significant bit in the byte representing key or button
8N.



                 39





X Input Extension Protocol Specification    X11, Release 6.4


If the device has valuators, a bit in the mode field indi-
cates whether the device is reporting Absolute or Relative
data.  If it is reporting Absolute data, the valuators array
will contain the current value of the valuators.  If it is
reporting Relative data, the valuators array will contain
undefined data.

If the device reports proximity information, a bit in the
mode field indicates whether the device is InProximity or
OutOfProximity.

3.  Events

The input extension creates input events analogous to the
core input events.  These extension input events are gener-
ated by manipulating one of the extension input devices.

3.1.  Button, Key, and Motion Events

DeviceKeyPress
DeviceKeyRelease
DeviceButtonPress,
DeviceButtonRelease
DeviceMotionNotify

     device: CARD8
     root, event: WINDOW
     child: Window or None
     same-screen: BOOL
     root-x, root-y, event-x, event-y: INT16
     detail: <see below>
     state: SETofKEYBUTMASK
     time: TIMESTAMP


These events are generated when a key, button, or valuator
logically changes state.  The generation of these logical
changes may lag the physical changes, if device event pro-
cessing is frozen.  Note that DeviceKeyPress and
DeviceKeyRelease are generated for all keys, even those
mapped to modifier bits.  The ``source'' of the event is the
window the pointer is in.  The window with respect to which
the event is normally reported is found by looking up the
hierarchy (starting with the source window) for the first
window on which any client has selected interest in the
event.    The actual window used for reporting can be modified
by active grabs and by the focus window.The window the event
is reported with respect to is called the ``event'' window.

The root is the root window of the ``source'' window, and
root-x and root-y are the pointer coordinates relative to
root's origin at the time of the event.  Event is the
``event'' window.  If the event window is on the same screen
as root, then event-x and event-y are the pointer



                 40





X Input Extension Protocol Specification    X11, Release 6.4


coordinates relative to the event window's origin.  Other-
wise, event-x and event-y are zero.  If the source window is
an inferior of the event window, then child is set to the
child of the event window that is an ancestor of (or is) the
source window.    Otherwise, it is set to None. The state com-
ponent gives the logical state of the buttons on the core X
pointer and modifier keys on the core X keyboard just before
the event.  The detail component type varies with the event
type:

+--------------------+-------------------+
|Event             | Component     |
+--------------------+-------------------+
|DeviceKeyPress,     | KEYCODE         |
|DeviceKeyRelease    |             |
+--------------------+-------------------+
|DeviceButtonPress,  | BUTTON         |
|DeviceButtonRelease |             |
+--------------------+-------------------+
|DeviceMotionNotify  | { Normal , Hint } |
+--------------------+-------------------+

The granularity of motion events is not guaranteed, but a
client selecting for motion events is guaranteed to get at
least one event when a valuator changes. If DeviceMotionHint
is selected, the server is free to send only one DeviceMo-
tionNotify event (with detail Hint) to the client for the
event window, until either a key or button changes state,
the pointer leaves the event window, or the client issues a
QueryDeviceState or GetDeviceMotionEvents request.

3.2.  DeviceValuator Event

DeviceValuator

     device: CARD8
     device_state: SETofKEYBUTMASK
     num_valuators: CARD8
     first_valuator: CARD8
     valuators: LISTofINT32


DeviceValuator events are generated to contain valuator
information for which there is insufficient space in
DeviceKey, DeviceButton, DeviceMotion, and Proximity wire
events.  For events of these types, a second event of type
DeviceValuator follows immediately.  The library combines
these events into a single event that a client can receive
via XNextEvent.  DeviceValuator events are not selected for
by clients, they only exist to contain information that will
not fit into some event selected by clients.

The device_state component gives the state of the buttons
and modifiers on the device generating the event.



                 41





X Input Extension Protocol Specification    X11, Release 6.4


Extension motion devices may report motion data for a vari-
able number of axes.  The valuators array contains the val-
ues of all axes reported by the device.  If more than 6 axes
are reported, more than one DeviceValuator event will be
sent by the server, and more than one DeviceKey, DeviceBut-
ton, DeviceMotion, or Proximity event will be reported by
the library.  Clients should examine the corresponding
fields of the event reported by the library to determine the
total number of axes reported, and the first axis reported
in the current event.  Axes are numbered beginning with
zero.

For Button, Key and Motion events on a device reporting
absolute motion data the current value of the device's valu-
ators is reported.  For devices that report relative data,
Button and Key events may be followed by a DeviceValuator
event that contains 0s in the num_valuators field.   In this
case, only the device_state component will have meaning.

3.3.  Device Focus Events

DeviceFocusIn
DeviceFocusOut

     device: CARD8
     time: TIMESTAMP
     event: WINDOW
     mode: { Normal, WhileGrabbed, Grab, Ungrab}
     detail: { Ancestor, Virtual, Inferior, Nonlinear, Non-
     linearVirtual, Pointer, PointerRoot, None}

These events are generated when the input focus changes and
are reported to clients selecting DeviceFocusChange for the
specified device and window.  Events generated by SetDevice-
Focus when the device is not grabbed have mode Normal.
Events generated by SetDeviceFocus when the device is
grabbed have mode WhileGrabbed.  Events generated when a
device grab actives have mode Grab, and events generated
when a device grab deactivates have mode Ungrab.

All DeviceFocusOut events caused by a window unmap are gen-
erated after any UnmapNotify event, but the ordering of
DeviceFocusOut with respect to generated EnterNotify,
LeaveNotify, VisibilityNotify and Expose events is not con-
strained.

DeviceFocusIn and DeviceFocusOut events are generated for
focus changes of extension devices in the same manner as
focus events for the core devices are generated.

3.4.  Device State Notify Event

DeviceStateNotify




                 42





X Input Extension Protocol Specification    X11, Release 6.4


     time: TIMESTAMP
     device: CARD8
     num_keys: CARD8
     num_buttons: CARD8
     num_valuators: CARD8
     classes_reported: CARD8 {SetOfDeviceMode | SetOfInput-
     Class}
      SetOfDeviceMode:
           #x80 ProximityState
            0 = InProxmity, 1 = OutOfProximity
           #x40 Device Mode
            (0 = Relative, 1 = Absolute)
      SetOfInputClass:
           #x04 reporting valuators
           #x02 reporting buttons
           #x01 reporting keys
     buttons: LISTofCARD8
     keys: LISTofCARD8
     valuators: LISTofCARD32


This event reports the state of the device just as in the
QueryDeviceState request.  This event is reported to clients
selecting DeviceStateNotify for the device and window and is
generated immediately after every EnterNotify and DeviceFo-
cusIn.    If the device has no more than 32 buttons, no more
than 32 keys, and no more than 3 valuators, This event can
report the state of the device.  If the device has more than
32 buttons, the event will be immediately followed by a
DeviceButtonStateNotify event.    If the device has more than
32 keys, the event will be followed by a DeviceKeyStateNo-
tify event.  If the device has more than 3 valuators, the
event will be followed by one or more DeviceValuator events.

3.5.  Device KeyState and ButtonState Notify Events

DeviceKeyStateNotify

     device: CARD8
     keys: LISTofCARD8

DeviceButtonStateNotify

     device: CARD8
     buttons: LISTofCARD8

These events contain information about the state of keys and
buttons on a device that will not fit into the DeviceS-
tateNotify wire event.    These events are not selected by
clients, rather they may immediately follow a DeviceStateNo-
tify wire event and be combined with it into a single
DeviceStateNotify client event that a client may receive via
XNextEvent.




                 43





X Input Extension Protocol Specification    X11, Release 6.4


3.6.  DeviceMappingNotify Event

DeviceMappingNotify

     time: TIMESTAMP
     device: CARD8
     request: CARD8
     first_keycode: CARD8
     count: CARD8

This event reports a change in the mapping of keys, modi-
fiers, or buttons on an extension device.  This event is
reported to clients selecting DeviceMappingNotify for the
device and window and is generated after every client SetDe-
viceButtonMapping, ChangeDeviceKeyMapping, or  ChangeDevice-
ModifierMapping request.

3.7.  ChangeDeviceNotify Event

ChangeDeviceNotify

     device: CARD8
     time: TIMESTAMP
     request: CARD8

This event reports a change in the physical device being
used as the core X keyboard or X pointer device.  ChangeDe-
viceNotify events are reported to clients selecting
ChangeDeviceNotify for the device and window and is gener-
ated after every client ChangeKeyboardDevice or  ChangePoin-
terDevice request.

3.8.  Proximity Events

ProximityIn
ProximityOut

     device: CARD8
     root, event: WINDOW
     child: Window or None
     same-screen: BOOL
     root-x, root-y, event-x, event-y: INT16
     state: SETofKEYBUTMASK
     time: TIMESTAMP
     device-state: SETofKEYBUTMASK
     axis-count: CARD8
     first-axis: CARD8
     axis-data: LISTofINT32


These events are generated by some devices (such as graphics
tablets or touchscreens) to indicate that a stylus has moved
into or out of contact with a positional sensing surface.




                 44





X Input Extension Protocol Specification    X11, Release 6.4


The ``source'' of the event is the window the pointer is in.
The window with respect to which the event is normally
reported is found by looking up the hierarchy (starting with
the source window) for the first window on which any client
has selected interest in the event.  The actual window used
for reporting can be modified by active grabs and by the
focus window.The window the event is reported with respect
to is called the ``event'' window.

The root is the root window of the ``source'' window, and
root-x and root-y are the pointer coordinates relative to
root's origin at the time of the event.  Event is the
``event'' window.  If the event window is on the same screen
as root, then event-x and event-y are the pointer coordi-
nates relative to the event window's origin.  Otherwise,
event-x and event-y are zero.  If the source window is an
inferior of the event window, then child is set to the child
of the event window that is an ancestor of (or is) the
source window.    Otherwise, it is set to None. The state com-
ponent gives the logical state of the buttons on the core X
pointer and modifier keys on the core X keyboard just before
the event.  The device-state component gives the state of
the buttons and modifiers on the device generating the
event.

































                 45





X Input Extension Protocol Specification    X11, Release 6.4




             Appendix A

         Input Extension Protocol Encoding



Syntactic Conventions

All numbers are in decimal, unless prefixed with #x, in
which case they are in hexadecimal (base 16).

The general syntax used to describe requests, replies,
errors, events, and compound types is:


     NameofThing
       encode-form
       ...
       encode-form

Each encode-form describes a single component.

For components described in the protocol as:


     name: TYPE

the encode-form is:


     N           TYPE name

N is the number of bytes occupied in the data stream, and
TYPE is the interpretation of those bytes.  For example,


     depth: CARD8

becomes:


     1           CARD8          depth

For components with a static numeric value the encode-form
is:


     N           value          name

The value is always interpreted as an N-byte unsigned inte-
ger.  For example, the first two bytes of a Window error are
always zero (indicating an error in general) and three



                 46





X Input Extension Protocol Specification    X11, Release 6.4


(indicating the Window error in particular):


     1           0    Error
     1           3    code

For components described in the protocol as:


     name: {Name1, ..., NameI}


the encode-form is:


     N            name
           value1 Name1
           ...
           valueI NameI

The value is always interpreted as an N-byte unsigned inte-
ger.  Note that the size of N is sometimes larger than that
strictly required to encode the values.  For example:


     class: {InputOutput, InputOnly, CopyFromParent}


becomes:


     2                  class
           0    CopyFromParent
           1    InputOutput
           2    InputOnly

For components described in the protocol as:


     NAME: TYPE or Alternative1 ... or AlternativeI


the encode-form is:


     N           TYPE          NAME
           value1     Alternative1
           ...
           valueI     AlternativeI

The alternative values are guaranteed not to conflict with
the encoding of TYPE.  For example:





                 47





X Input Extension Protocol Specification    X11, Release 6.4


     destination: WINDOW or PointerWindow or InputFocus


becomes:


     4           WINDOW          destination
           0    PointerWindow
           1    InputFocus

For components described in the protocol as:


     value-mask: BITMASK

the encode-form is:


     N           BITMASK          value-mask
           mask1     mask-name1
           ...
           maskI     mask-nameI

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-sig-
nificant 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.

For LISTofVALUE encodings, the request is followed by a sec-
tion of the form:


     VALUEs
      encode-form
      ...
      encode-form

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 num-
ber 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.

In various cases, the number of bytes occupied by a compo-
nent will be specified by a lowercase single-letter variable
name instead of a specific numeric value, and often some



                 48





X Input Extension Protocol Specification    X11, Release 6.4


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:


     2           3+n          request length
     4n        LISTofPOINT    points

For unused bytes (the values of the bytes are undefined and
do not matter), the encode-form is:


     N             unused

If the number of unused bytes is variable, the encode-form
typically is:


     p             unused, p=pad(E)

where E is some expression, and pad(E) is the number of
bytes needed to round E up to a multiple of four.


     pad(E) = (4 - (E mod 4)) mod 4

Common Types

LISTofFOO

     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.

SETofFOO

     A set is always represented by a bitmask, with a 1-bit
     indicating presence in the set.

BITMASK: CARD32

WINDOW: CARD32

BYTE: 8-bit value

INT8: 8-bit signed integer

INT16: 16-bit signed integer

INT32: 32-bit signed integer




                 49





X Input Extension Protocol Specification    X11, Release 6.4


CARD8: 8-bit unsigned integer

CARD16: 16-bit unsigned integer

CARD32: 32-bit unsigned integer

TIMESTAMP: CARD32

EVENTCLASS: CARD32


INPUTCLASS
       0     KeyClass
       1     ButtonClass
       2     ValuatorClass
       3     FeedbackClass
       4     ProximityClass
       5     FocusClass
       6     OtherClass



INPUTCLASS
       0     KbdFeedbackClass
       1     PtrFeedbackClass
       2     StringFeedbackClass
       3     IntegerFeedbackClass
       4     LedFeedbackClass
       5     BellFeedbackClass



INPUTINFO
       0     KEYINFO
       1     BUTTONINFO
       2     VALUATORINFO



DEVICEMODE
       0     Relative
       1     Absolute



PROXIMITYSTATE
       0     InProximity
       1     OutOfProximity









                 50





X Input Extension Protocol Specification    X11, Release 6.4


BOOL
       0     False
       1     True


KEYSYM: CARD32

KEYCODE: CARD8

BUTTON: CARD8


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



SETofKEYMASK
       encodings are the same as for SETofKEYBUTMASK, except with
       #xff00     unused but must be zero


STRING8: LISTofCARD8


STR
  1  n             length of name in bytes
  n  STRING8         name

Errors


Request
  1  0             Error
  1  1             code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused




                 51





X Input Extension Protocol Specification    X11, Release 6.4


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



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



Match
  1  0             Error
  1  8             code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Access
  1  0             Error
  1  10          code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Alloc
  1  0             Error
  1  11          code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused





                 52





X Input Extension Protocol Specification    X11, Release 6.4


Name
  1  0             Error
  1  15          code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Device
  1  0             Error
  1  CARD8         code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Event
  1  0             Error
  1  CARD8         code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Mode
  1  0             Error
  1  CARD8         code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused



Class
  1  0             Error
  1  CARD8         code
  2  CARD16         sequence number
  4             unused
  2  CARD16         minor opcode
  1  CARD8         major opcode
  21             unused

Keyboards



                 53





X Input Extension Protocol Specification    X11, Release 6.4


KEYCODE values are always greater than 7 (and less than
256).

KEYSYM values with the bit #x10000000 set are reserved as
vendor-specific.

The names and encodings of the standard KEYSYM values are
contained in appendix F.

Pointers

BUTTON values are numbered starting with one.

Requests


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)


 =>
  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



ListInputDevices
  1  CARD8         input extension opcode
  1  2             ListInputDevices opcode
  2  1             request length


 =>
  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)




                 54





X Input Extension Protocol Specification    X11, Release 6.4


  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)



  INPUTINFO    KEYINFO or BUTTONINFO or VALUATORINFO



  KEYINFO
  1  0             class id
  1  8             length
  1  KEYCODE         minimum keycode
  1  KEYCODE         maximum keycode
  2  CARD16         number of keys
  2             unused



BUTTONINFO
  1  1             class id
  1  4             length
  2  CARD16         number of buttons



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



AXISINFO
  4  CARD32         resolution
  4  CARD32         minimum value
  4  CARD32         maximum value







                 55





X Input Extension Protocol Specification    X11, Release 6.4


OpenDevice
  1  CARD8         input extension opcode
  1  3             OpenDevice opcode
  2  2             request length
  1  CARD8         device id
  3             unused


 =>
  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)



  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



CloseDevice
  1  CARD8         input extension opcode
  1  4             CloseDevice opcode
  2  2             request length
  1  CARD8         device id
  3             unused



SetDeviceMode
  1  CARD8         input extension opcode
  1  5             SetDeviceMode opcode
  2  2             request length
  1  CARD8         device id
  1  CARD8         mode
  2             unused








                 56





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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



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



GetSelectedExtensionEvents
  1  CARD8         input extension opcode
  1  7             GetSelectedExtensionEvents opcode
  2  2             request length
  4  Window         event window


 =>
  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
















                 57





X Input Extension Protocol Specification    X11, Release 6.4


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



GetDeviceDontPropagateList
  1  CARD8         input extension opcode
  1  9             GetDeviceDontPropagateList opcode
  2  2             request length
  4  Window         event window


 =>
  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



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















                 58





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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      LISTofDEVICETIMECOORDevents



  DEVICETIMECOORD
  4  TIMESTAMP         time
  4m LISTofINT32     valuators



ChangeKeyboardDevice
  1  CARD8         input extension opcode
  1  11          ChangeKeyboardDevice opcode
  2  2             request length
  1  CARD8         device id
  3             unused


 =>
  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



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







                 59





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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



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


 =>
  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












                 60





X Input Extension Protocol Specification    X11, Release 6.4


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



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



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








                 61





X Input Extension Protocol Specification    X11, Release 6.4


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



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



















                 62





X Input Extension Protocol Specification    X11, Release 6.4


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



GetDeviceFocus
  1  CARD8         input extension opcode
  1  20          GetDeviceFocus opcode
  2  2             request length
  1  CARD8         device
  3             unused


 =>
  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















                 63





X Input Extension Protocol Specification    X11, Release 6.4


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



GetFeedbackControl
  1  CARD8         input extension opcode
  1  22          GetFeedbackControl opcode
  2  2             request length
  1  CARD8         device id
  3             unused


 =>
  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



  FEEDBACKSTATE      KBDFEEDBACKSTATE, PTRFEEDBACKSTATE, INTEGERFEEDBACKSTATE,
  STRINGFEEDBACKSTATE, BELLFEEDBACKSTATE, or LEDFEEDBACKSTATE
















                 64





X Input Extension Protocol Specification    X11, Release 6.4


  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



  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



  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



  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











                 65





X Input Extension Protocol Specification    X11, Release 6.4


  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



  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



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



  FEEDBACKCLASS      KBDFEEDBACKCTL, PTRFEEDBACKCTL, INTEGERFEEDBACKCTL,
  STRINGFEEDBACKCTL, BELLFEEDBACKCTL, or LEDFEEDBACKCTL








                 66





X Input Extension Protocol Specification    X11, Release 6.4


  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



  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



  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



  INTEGERCTL
  1  3             feedback class id
  1  CARD8         id of this feedback
  2  8             length
  4  INT32         integer to display













                 67





X Input Extension Protocol Specification    X11, Release 6.4


  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



  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



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


 =>
  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



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





                 68





X Input Extension Protocol Specification    X11, Release 6.4


GetDeviceModifierMapping
  1  CARD8         input extension opcode
  1  26          GetDeviceModifierMapping opcode
  2  2             request length
  1  CARD8         device
  3             unused


 =>
  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



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


 =>
  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



GetDeviceButtonMapping
  1  CARD8         input extension opcode
  1  28          GetDeviceButtonMapping opcode
  2  2             request length
  1  CARD8         device
  3             unused









                 69





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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)



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)


 =>
  1  1             Reply
  1  29          SetDeviceButtonMapping opcode
  2  CARD16         sequence number
  4  0             reply length
  1             status
     0           Success
     1           Busy
  23             unused



QueryDeviceState
  1  CARD8         input extension opcode
  1  30          QueryDeviceState opcode
  2  2             request length
  1  CARD8         device
  3             unused


 =>
  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






                 70





X Input Extension Protocol Specification    X11, Release 6.4


  INPUTSTATE   KEYSTATE or BUTTONSTATE or VALUATORSTATE



  KEYSTATE
  1  CARD8         key input class id
  1  36          length
  1  CARD8         num_keys
  1             unused
  32 LISTofCARD8     status of keys


  BUTTONSTATE
  1  CARD8         button input class id
  1  36          length
  1  CARD8         num_buttons
  1             unused
  32 LISTofCARD8     status of buttons


  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



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           LISTofEVENTSevents to send
  4m LISTofEVENTCLASS     desired events














                 71





X Input Extension Protocol Specification    X11, Release 6.4


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



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


 =>
  1  1                   Reply
  1  33                SetDeviceValuators opcode
  2  CARD16               sequence number
  4  0                   reply length
  1  CARD8               status
     0           Success
     1           AlreadyGrabbed
  23                   unused



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
















                 72





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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


DEVICESTATE         DEVICERESOLUTIONSTATE



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




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


DEVICECONTROL         DEVICERESOLUTIONCTL



DEVICERESOLUTIONCTL
  2  1             control type
  2  8 + 4n         length
  1  CARD8         first_valuator
  1  n             num_valuators
  2             unused
  4n LISTOfCARD32     resolution values








                 73





X Input Extension Protocol Specification    X11, Release 6.4


 =>
  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

Events

DeviceKeyPress, DeviceKeyRelease, DeviceButtonPress, Device-
ButtonRelease, ProximityIn, ProximityOut, and DeviceStateNo-
tify  events may be followed by zero or more DeviceValuator
events.  DeviceMotionNotify events will be followed by one
or more DeviceValuator events.


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



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









                 74





X Input Extension Protocol Specification    X11, Release 6.4


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



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




















                 75





X Input Extension Protocol Specification    X11, Release 6.4


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



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


















                 76





X Input Extension Protocol Specification    X11, Release 6.4


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



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












                 77





X Input Extension Protocol Specification    X11, Release 6.4


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



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


DeviceStateNotify events may be immediately followed by zero
or one DeviceKeyStateNotify and/ or zero or more DeviceValu-
ator events.















                 78





X Input Extension Protocol Specification    X11, Release 6.4


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)



DeviceKeyStateNotify
  1  CARD8         code
  1  CARD8         device id
     #x80         MORE_EVENTS follow
  2  CARD16         sequence number
  28 LISTofCARD8     state of keys 33-255



DeviceButtonStateNotify
  1  CARD8         code
  1  CARD8         device id
     #x80         MORE_EVENTS follow
  2  CARD16         sequence number
  28 LISTofCARD8     state of buttons 33-255



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










                 79





X Input Extension Protocol Specification    X11, Release 6.4


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



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
































                 80








             Table of Contents


1.1. Input Extension Overview  . . . . . . . . . . . . .   1
1.2. Design Approach . . . . . . . . . . . . . . . . . .   1
1.3. Core Input Devices  . . . . . . . . . . . . . . . .   1
1.4. Extension Input Devices . . . . . . . . . . . . . .   2
1.4.1. Event Classes . . . . . . . . . . . . . . . . . .   3
1.4.2. Input Classes . . . . . . . . . . . . . . . . . .   3
2. Requests  . . . . . . . . . . . . . . . . . . . . . .   4
2.1. Getting the Extension Version . . . . . . . . . . .   4
2.2. Listing Available Devices . . . . . . . . . . . . .   4
2.3. Enabling Devices  . . . . . . . . . . . . . . . . .   8
2.4. Changing The Mode Of A Device . . . . . . . . . . .   9
2.5. Initializing Valuators on an Input Device . . . . .  10
2.6. Getting Input Device Controls . . . . . . . . . . .  10
2.7. Selecting Extension Device Events . . . . . . . . .  13
2.8. Determining Selected Events . . . . . . . . . . . .  14
2.9. Controlling Event Propagation . . . . . . . . . . .  14
2.10. Sending Extension Events . . . . . . . . . . . . .  15
2.11. Getting Motion History . . . . . . . . . . . . . .  16
2.12. Changing The Core Devices  . . . . . . . . . . . .  16
2.13. Event Synchronization And Core Grabs . . . . . . .  19
2.14. Extension Active Grabs . . . . . . . . . . . . . .  19
2.15. Passively Grabbing A Key . . . . . . . . . . . . .  21
2.16. Passively Grabbing A Button  . . . . . . . . . . .  23
2.17. Thawing A Device . . . . . . . . . . . . . . . . .  25
2.18. Controlling Device Focus . . . . . . . . . . . . .  27
2.19. Controlling Device Feedback  . . . . . . . . . . .  29
2.20. Ringing a Bell on an Input Device  . . . . . . . .  34
2.21. Controlling Device Encoding  . . . . . . . . . . .  34
2.22. Controlling Button Mapping . . . . . . . . . . . .  38
2.23. Obtaining The State Of A Device  . . . . . . . . .  39
3. Events  . . . . . . . . . . . . . . . . . . . . . . .  40
3.1. Button, Key, and Motion Events  . . . . . . . . . .  40
3.2. DeviceValuator Event  . . . . . . . . . . . . . . .  41
3.3. Device Focus Events . . . . . . . . . . . . . . . .  42
3.4. Device State Notify Event . . . . . . . . . . . . .  42
3.5. Device KeyState and ButtonState Notify Events
 . . . . . . . . . . . . . . . . . . . . . . . . . . . .  43
3.6. DeviceMappingNotify Event . . . . . . . . . . . . .  44
3.7. ChangeDeviceNotify Event  . . . . . . . . . . . . .  44
3.8. Proximity Events  . . . . . . . . . . . . . . . . .  44
Appendix A - Input Extension Protocol Encoding . . . . .  46













                  i