fdo-mirrors/xorg-xorgproto
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/xorg/proto/xorgproto.git synced 2026-05-05 07:38:10 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add touch classes and events, bump to 2.1

Browse source 
Introduce multitouch support through a new TouchClass, as well as new
TouchBegin, TouchEnd, TouchOwnership, TouchUpdate, and TouchUpdateUnowned
events.  Bump to version 2.1.

Signed-off-by: Daniel Stone <daniel@fooishbar.org>
Co-authored-by: Chase Douglas <chase.douglas@canonical.com>
Co-authored-by: Peter Hutterer <peter.hutterer@who-t.net>
This commit is contained in:
Daniel Stone 2011-02-07 10:19:06 +00:00
parent 13baef91f0
commit 99f15a2346
4 changed files with 514 additions and 17 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
XI2.h
View file

@ -36,6 +36,7 @@
#define XI_2_Major 2
#define XI_2_Minor 0
#define XI_2_1_Minor 1
/* Property event flags */
#define XIPropertyDeleted 0
@ -65,6 +66,8 @@
#define XIGrabtypeKeycode 1
#define XIGrabtypeEnter 2
#define XIGrabtypeFocusIn 3
#define XIGrabtypeTouchBegin 4
#define XIGrabtypeTouchBeginInert 5
/* Passive grab modifier */
#define XIAnyModifier (1U << 31)
@ -79,6 +82,11 @@
#define XIAsyncPair 4
#define XISyncPair 5
/* XIAllowTouchEvents bitmask event-modes */
#define XITouchOwnerAccept (1 << 0)
#define XITouchOwnerRejectEnd (1 << 1)
#define XITouchOwnerRejectContinue (1 << 2)
/* DeviceChangedEvent change reasons */
#define XISlaveSwitch 1
#define XIDeviceChange 2
@ -113,15 +121,27 @@
#define XISlaveKeyboard 4
#define XIFloatingSlave 5
/* Device classes */
/* Device classes: classes that are not identical to Xi 1.x classes must be
* numbered starting from 8. */
#define XIKeyClass 0
#define XIButtonClass 1
#define XIValuatorClass 2
#define XITouchClass 8
#define XITouchValuatorClass 9
/* Device event flags (common) */
/* Device event flags (key events only) */
#define XIKeyRepeat (1 << 16)
/* Device event flags (pointer events only) */
#define XIPointerEmulated (1 << 16)
/* Device event flags (touch events only) */
#define XITouchPendingEnd (1 << 16)
/* Device event flags (touch end events only) */
#define XITouchAccepted (1 << 17)
/* Touch modes */
#define XIDirectTouch 1
#define XIDependentTouch 2
/* XI2 event mask macros */
#define XISetMask(ptr, event) (((unsigned char*)(ptr))[(event)>>3] |= (1 << ((event) & 7)))
@ -151,7 +171,12 @@
#define XI_RawButtonPress 15
#define XI_RawButtonRelease 16
#define XI_RawMotion 17
#define XI_LASTEVENT XI_RawMotion
#define XI_TouchBegin 18
#define XI_TouchEnd 19
#define XI_TouchOwnership 20
#define XI_TouchUpdate 21
#define XI_TouchUpdateUnowned 22
#define XI_LASTEVENT XI_TouchUpdateUnowned
/* NOTE: XI2LASTEVENT in xserver/include/inputstr.h must be the same value
* as XI_LASTEVENT if the server is supposed to handle masks etc. for this
* type of event. */
@ -177,5 +202,10 @@
#define XI_RawButtonPressMask (1 << XI_RawButtonPress)
#define XI_RawButtonReleaseMask (1 << XI_RawButtonRelease)
#define XI_RawMotionMask (1 << XI_RawMotion)
#define XI_TouchBeginMask (1 << XI_TouchBegin)
#define XI_TouchEndMask (1 << XI_TouchEnd)
#define XI_TouchOwnershipChangedMask (1 << XI_TouchOwnershipChanged)
#define XI_TouchUpdateMask (1 << XI_TouchUpdate)
#define XI_TouchUpdateUnownedMask (1 << XI_TouchUpdateUnowned)
#endif /* _XI2_H_ */

64
XI2proto.h
View file

@ -92,9 +92,10 @@
#define X_XIDeleteProperty 58
#define X_XIGetProperty 59
#define X_XIGetSelectedEvents 60
#define X_XIAllowTouchEvents 61
/** Number of XI requests */
#define XI2REQUESTS (X_XIGetSelectedEvents - X_XIQueryPointer + 1)
#define XI2REQUESTS (X_XIAllowTouchEvents - X_XIQueryPointer + 1)
/** Number of XI2 events */
#define XI2EVENTS (XI_LASTEVENT + 1)
@ -188,6 +189,31 @@ typedef struct {
uint16_t pad2;
} xXIValuatorInfo;
/**
* Denotes multitouch capability on a device.
*/
typedef struct {
uint16_t type; /**< Always TouchClass */
uint16_t length; /**< Length in 4 byte units */
uint16_t sourceid; /**< source device for this class */
uint8_t mode; /**< DirectTouch or DependentTouch */
uint8_t num_touches; /**< Maximum number of touches (0==unlimited) */
} xXITouchInfo;
/**
* Denotes a multitouch valuator capability on a device.
* One XITouchValuatorInfo describes exactly one valuator (axis) on the device.
*/
typedef struct {
uint16_t type; /**< Always TouchValuatorClass */
uint16_t length; /**< Length in 4 byte units */
uint16_t sourceid; /**< source device for this class */
uint16_t number; /**< Valuator number */
Atom label; /**< Axis label */
FP3232 min; /**< Min value */
FP3232 max; /**< Max value */
uint32_t resolution; /**< Resolutions in units/m */
} xXITouchValuatorInfo;
/**
* Used to select for events on a given window.
@ -772,6 +798,20 @@ typedef struct {
} xXIGetPropertyReply;
#define sz_xXIGetPropertyReply 32
/**
* Accept or reject a grabbed touch sequence.
*/
typedef struct {
uint8_t reqType;
uint8_t ReqType; /**< Always ::X_XIAllowTouchEvents */
uint16_t length; /**< Length in 4 byte units */
uint32_t touchid;
uint16_t deviceid;
uint8_t mode; /**< bitmask */
uint8_t pad;
} xXIAllowTouchEventsReq;
#define sz_xXIAllowTouchEventsReq 12
/*************************************************************************************
* *
* EVENTS *
@ -857,7 +897,27 @@ typedef struct
} xXIDeviceChangedEvent;
/**
* Default input event for pointer or keyboard input.
* The owner of a touch stream has passed on ownership to another client.
*/
typedef struct
{
uint8_t type; /**< Always GenericEvent */
uint8_t extension; /**< XI extension offset */
uint16_t sequenceNumber;
uint32_t length; /**< Length in 4 byte units */
uint16_t evtype; /**< XI_TouchOwnership */
uint16_t deviceid; /**< Device that has changed */
Time time;
uint16_t sourceid; /**< Source of the new classes */
uint16_t pad0;
uint32_t touchid;
uint32_t flags;
uint32_t pad1;
uint32_t pad2;
} xXITouchOwnershipEvent;
/**
* Default input event for pointer, keyboard or touch input.
*/
typedef struct
{

431
XI2proto.txt
View file

@ -1,11 +1,20 @@
The X Input Extension
Version 2.0
Version 2.1
Peter Hutterer
peter.hutterer@redhat.com
Red Hat, Inc.
Daniel Stone
daniel@fooishbar.org
Collabora, Ltd.
Chase Douglas
chase.douglas@canonical.com
Canonical, Ltd.
1. Introduction
@ -31,6 +40,41 @@ used on applications employing the core protocol. XI2 addresses both of these
issues by enabling devices to be both extended and core devices and providing
device information in each event (with the exception of core events).
1.1 X Input Extension version 2.1 (XI 2.1)
XI 2.1 introduces support for multi-touch devices. The traditional
pointer/keyboard approach enforced by XI 2.0 with the master/slave device
hierarchy is not always suitable for multi-touch devices that can provide a
dynamic number of multiple independent input points per physical device.
Furthermore, as such devices are often direct input devices (e.g. touchscreens,
able to focus without a pointer), the virtual abstraction of master devices is
not always necessary.
The additions in XI 2.1 aim to:
- support a dynamic number of simultaneous touch points,
- support devices that are both multi-touch and traditional pointer devices,
- while supporting pre-XI2.1 clients through emulation of XI 2.0 and core
pointer events.
XI 2.1 caters for two modes of touch input devices:
- direct multi-touch input devices such as touch screens. These devices
provide independent touchpoints that can occur anywhere on the screen and
are usually the result of direct touch interaction.
- indirect touch input devices such as multi-touch trackpads. These devices
provide independent touchpoints that may need to be interpreted
relative to the current position of the pointer on that same device. Such
interactions are usually the result of a gesture performed on the device.
A device may change its touch mode at runtime. Clients are informed which
type of touch device they are dealing with. See XIQueryDevice for more
information.
Touch device support is only available to clients supporting version 2.1 or
later of the X Input Extension. Clients must use the XIQueryVersion request to
announce support of this version.
XI 2.1 requires devices to track touch points over time. Devices that cannot
do so in hardware must employ software trackers to be usable with XI 2.1.
❧❧❧❧❧❧❧❧❧❧❧
2. Notations used in this document
@ -149,7 +193,76 @@ to P is only attempted if neither the XI event, nor the core event has been
delivered on W. Once an event has been delivered as either XI or core event,
event processing stops.
4.4. The ClientPointer principle
4.4 Touch device support
Touch event processing differs from normal event processing in a few ways,
most notably in that touch events are processed partially out-of-band from
pointer and keyboard events.
Touch input follows a three-stage cycle: init - move - move - ... - destroy,
i.e. “init” the sequence by touching the device, “move” the current touch
location any number of times, and finally “destroy” the sequence by ceasing
to touch the device. The init and destroy stage of this sequence are always
present, while the move stage is optional. Within this document, the term
"touch sequence" is used to describe the above chain of events. A client
wishing to receive touch events must register for at least TouchBegin,
TouchOwnership, TouchUpdate, and TouchEnd simultaneously; it may also select
for TouchUpdateUnowned events if it wants to receive the full touch stream,
rather than just the final state.
A touch sequence is only considered to be meaningful in its entirety: clients
may not capture part of a touch sequence, interpret only that part, and then
pass a partial touch sequence on to the next client. To this end, all clients
with active “grabs” on the window hierarchy for a touch sequence receive events
from that touch sequence, as well as the client with the deepest selection
(i.e. furthest from the root window). Clients currently in control of the
touch sequence receive TouchUpdate events, whereas clients not in control
receive TouchUpdateUnowned events.
Touch grabs are similar to standard input event grabs in that they take
precedence over selections and are searched from the root window to the child
window. The first grab found for a touch sequence will be the owner of that
touch sequence, however events for that touch sequence will continue to be
delivered to all clients with grabs in the window tree, as well as the client
with the deepest selection. The first client may either “accept” the touch,
which claims the touch sequence and stops delivery to all other clients for
the duration of the touch sequence, or “reject” the touch sequence, which
will remove that client from the delivery set and pass ownership on to the
next client.
Window sets for direct device touches contain the windows from the root to the
child in which the touch originated.
Dependent device window sets depend on whether other touches are active. For
the first dependent touch on a device, the window set contains the windows from
the root to the current window underneath the position of the device's pointer.
For subsequent touches on this device, the window set is identical to
the window set of the first touch. Once all touches have been released, the
window set is reset and re-calculated on the first subsequent touch.
No touches from a dependent device may begin while the device is floating, as
it does not have an associated pointer position to focus events.
If there is no touch grab on a window and the server supports pointer
emulation, it will look for a pointer grab on that window and include it as
part of the delivery set; similarly, if no client has selected to receive
touch events on a window, the server may look for pointer event selections
on that window to add to the delivery set.
The delivery of touch events is not changed by any modifications to the window
hierarchy after the window set has been determined for the touch, nor is it
affected by new grabs or selections.
A TouchEnd event will always be sent to a client when it will receive no more
events from a particular touch, regardless of why (grab or selection removed,
owner accepted, the client having rejected that touch, etc).
A device that sends touch events may also generate pointer events on demand.
The decision of which touch events are converted into pointer events is
implementation-specific, however any pointer event generated from a touch
event will have the PointerEmulated flag set. Emulated pointer/keyboard events
follow the core and XI2 grab semantics.
4.5. The ClientPointer principle
Many core protocol and some extension requests are ambiguous when multiple
master devices are available (e.g. QueryPointer does not specfy which pointer).
@ -271,7 +384,7 @@ are required to be 0.
name: LISTofCHAR8
classes: LISTofCLASS }
CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS }
CLASS { BUTTONCLASS, KEYCLASS, AXISCLASS, TOUCHCLASS*, TOUCHAXISCLASS* }
BUTTONCLASS { type: ButtonClass
length: CARD16
@ -296,6 +409,26 @@ are required to be 0.
value: FP3232
resolution: CARD32 }
TOUCHCLASS* { type: TouchClass
length: CARD16
sourceid: CARD16
mode: TOUCHMODE
num_touches: CARD16 }
TOUCHAXISCLASS* {
type: TouchAxisClass
length: CARD16
sourceid: CARD16
axisnumber: CARD16
label: ATOM
min: FP3232
max: FP3232
resolution: CARD32 }
TOUCHMODE* { DirectTouch, DependentTouch }
* since XI 2.1
XIQueryDevice details information about the requested input devices.
devices
@ -397,6 +530,54 @@ are required to be 0.
An axis in Relative mode may specify min and max as a hint to the
client. If no min and max information is available, both must be 0.
XI 2.1:
TouchClass:
type
Always TouchClass.
length
Length in 4 byte units.
sourceid
The device this class originates from.
mode
The device type of the touch device. Touch sequences from a device
of type DirectTouch should be interpreted as directly occuring on
the position they are reported on. Touch sequences from a device of
type DependentTouch should be interpreted as dependent of the
current position of the pointer.
num_touches
The maximum number of simultaneous touchpoints the device may send.
If num_touches is 0, the number of supported touches is unknown or
unlimited.
A device with a TouchClass must provide one or more TOUCHAXISCLASS
specifiers.
TouchAxisClass:
type
Always TouchAxisClass.
length
Length in 4 byte units.
sourceid
The device this class originates from.
axisnumber
Axis number of this axis. The axis number is in device-native
order and potential axis mappings are ignored.
label
Atom specifying the axis name. An Atom of None specifies an unlabeled
axis.
min
Minimum value for this axis.
max
Maximum value for this axis.
resolution
Resolution in counts/meter.
Devices generating touch events must provide exactly one TouchClass and
two or more TouchAxisClasses. TouchAxisClasses and AxisClasses are not
interchangable. A TouchAxisClass may only be part of a touch event,
whereas an AxisClass may only be part of non-touch events.
┌───
XISelectEvents
window: Window
@ -439,6 +620,14 @@ are required to be 0.
The mask for XIHierarchyEvents may only be selected for XIAllDevices.
Setting it for any other device results in a BadValue error.
A client selecting for any of XI_TouchBegin, XI_TouchOwnership,
XI_TouchUpdate or XI_TouchEnd must select for all three events at the
same time, else BadValue will be returned. A client selecting for
XI_TouchUpdateUnowned must select for all three of the other touch
events. If the selection for these touch events overlaps a current
selection by another client (e.g. selecting for a specific device when
another client has a selection for XIAllDevices), a BadAccess error occurs.
┌───
XIGetSelectedEvents
window: Window
@ -794,7 +983,8 @@ are required to be 0.
This request actively grabs control of the specified input device. Further
input events from this device are reported only to the grabbing client.
This request overides any previous active grab by this client for this
device.
device. This request does not, however, affect the processing of XI 2.1
touch events.
deviceid
The device to grab.
@ -999,7 +1189,8 @@ are required to be 0.
└───
GRABTYPE { GrabtypeButton, GrabtypeKeycode, GrabtypeEnter,
GrabtypeFocusIn}
GrabtypeFocusIn, GrabtypeTouchBegin,
GrabtypeTouchBeginInert }
GRABMODIFIERINFO { status: Access
modifiers: CARD32 }
@ -1015,7 +1206,8 @@ are required to be 0.
AllMasterDevices.
detail
The button number, or key symbol to grab for.
Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
GrabtypeTouchBegin.
grab_type
The type of grab to establish.
grab_window
@ -1030,6 +1222,8 @@ are required to be 0.
releasing XIAllowEvents request or until the device grab is
released. Actual device input events are not lost while the device
is frozen; they are simply queued for later processing.
Must be Asynchronous for GrabtypeTouchBegin and
GrabtypeTouchBeginInert (see section 4.4).
mask_len
Length of mask in 4 byte units.
mask
@ -1087,6 +1281,16 @@ are required to be 0.
- a passive grab of the same grab_type + modifier combination does not
does not exist on an ancestor of grab_window.
Or if grab_type is GrabtypeTouchBegin or GrabtypeTouchBeginInert, a
touch grab (see section 4.4) begins if:
- a touch begins in grab_window or one of its ancestors, and
- the specified modifier keys are down
Ownership of the touch sequence is granted to the grabbing client if:
- grab_type is not GrabtypeTouchBeginInert, and
- a TouchBegin, TouchBeginInert, or pointer passive grab with the same
modifier set does not exist on an ancestor of grab_window, or all
applicable grabs have released ownership.
A modifier of GrabAnyModifier is equivalent to issuing the request for
all possible modifier combinations (including no modifiers). A client
may request a grab for GrabAnyModifier and explicit modifier
@ -1097,6 +1301,9 @@ are required to be 0.
A GrabtypeEnter or GrabtypeFocusIn grab is released when the
pointer or focus leaves the window and all of its descendants,
independent of the state of modifier keys.
A GrabtypeTouchBegin or GrabtypeTouchBeginInert grab is released when
the touch sequence ends, or a client uses XIAllowTouchEvents to reject
the touch and remove itself from the touch delivery sequence.
Note that the logical state of a device (as seen by means of the
protocol) may lag the physical state if device event processing is
frozen.
@ -1109,10 +1316,11 @@ are required to be 0.
with the same button or keycode and modifier combination, the
failed modifier combinations is returned in modifiers_return. If some
other client already has issued an XIPassiveGrabDevice request of
grab_type XIGrabtypeEnter or XIGrabtypeFocusIn with the same
grab_window and the same modifier combination, the failed modifier
combinations are returned in modifiers_return. If num_modifiers_return
is zero, all passive grabs have been successful.
grab_type XIGrabtypeEnter, XIGrabtypeFocusIn, XIGrabtypeTouchBegin, or
XIGrabtypeTouchBeginInert with the same grab_window and the same
modifier combination, the failed modifier combinations are returned
in modifiers_return. If num_modifiers_return is zero, all passive
grabs have been successful.
If a button grab or enter grab activates, EnterNotify and LeaveNotify
events with mode Grab are generated as if the pointer were to suddenly
@ -1133,6 +1341,11 @@ are required to be 0.
XIPassiveUngrabNotify are generated and sent to the grabbing client
before the grab deactivates.
See section 4.4 for additional notes on touch grabs, as they do not
behave like traditional grabs: in particular, they do not freeze the
device, and delivery of touch events continues even if the device is
frozen due to a grab by another client.
┌───
XIPassiveUngrabDevice
deviceid: DEVICEID
@ -1149,7 +1362,8 @@ are required to be 0.
The device to establish the passive grab on.
detail
The button number or key symbol to ungrab.
Must be 0 for GrabtypeEnter and GrabtypeFocusIn.
Must be 0 for GrabtypeEnter, GrabtypeFocusIn, and
GrabtypeTouchBegin.
grab_type
The type of grab to establish.
grab_window
@ -1308,6 +1522,44 @@ are required to be 0.
deleted from the device, and a XIPropertyNotify event is generated on
the device.
┌───
XIAllowTouchEvents: (since XI 2.1)
deviceid: DEVICEID
touchid: CARD32
event_mode: ALLOWTOUCHMODE
flags: SETofALLOWTOUCHFLAGS
└───
ALLOWTOUCHMODE { TouchOwnerAccept, TouchOwnerRejectEnd,
TouchOwnerRejectContinue }
ALLOWTOUCHFLAGS (none currently defined)
The XIAllowTouchEvents request allows the current owner of a touch
sequence to direct further delivery.
deviceid
The grabbed device ID.
touchid
The ID of the currently-grabbed touch sequence.
event_mode
Given TouchOwnerAccept, the client is deemed to have taken control
of the touch sequence; TouchEnd events will be sent to all other
clients listening to the touch sequence, and they will no longer
receive any TouchUpdate events.
Given TouchOwnerRejectEnd, the client is no longer interested in the
touch sequence, and will receive a TouchEnd event; ownership will be
passed on to the next listener.
Given TouchOwnerRejectContinue, the client is not interested in
ownership, but still wishes to receive TouchUpdate events;
ownership will be passed on to the next listener.
flags
A bitmask of applicable flags.
A BadValue error occurs if the touch ID is invalid, or BadAccess if this
client is not the current owner of the specified touch ID. BadValue errors
also occur if an invalid value is given for event_mode. Any flags not
understood by the server will be ignored.
8. Events:
@ -1338,6 +1590,12 @@ Version 2.0:
FocusIn
FocusOut
PropertyEvent
Version 2.1:
TouchBegin
TouchUpdate
TouchUpdateUnowned
TouchOwnership
TouchEnd
All events have a set of common fields specified as EVENTHEADER.
@ -1481,15 +1739,20 @@ EVENTHEADER { type: BYTE
DEVICEEVENTFLAGS (all events): none
DEVICEEVENTFLAGS (key events only): { KeyRepeat }
DEVICEEVENTFLAGS (pointer events only): none
DEVICEEVENTFLAGS (pointer events only): { PointerEmulated }
DEVICEEVENTFLAGS (touch events only): { TouchPendingEnd }
DEVICEEVENTFLAGS (touch end events only): { TouchAccepted }
An XIDeviceEvent is generated whenever the logical state of a device
changes in response to a button press, a button release, a motion, a key
press or a key release. The event type may be one of KeyPress,
KeyRelease, ButtonPress, ButtonRelease, Motion.
XI 2.1: The event type may also be TouchBegin, TouchUpdate,
TouchUpdateUnowned, or TouchEnd.
detail
The button number or key code, or 0.
The button number, key code, touch ID, or 0.
root
event
child
@ -1517,8 +1780,12 @@ EVENTHEADER { type: BYTE
Button state before the event.
valuators
Bitmask of valuators provided in axisvalues.
XI 2.1: For event types TouchBegin, TouchUpdate, TouchUpdateUnowned, and
TouchEnd, the valuators are those specified as TouchAxisClass.
axisvalues
Valuator data in device-native resolution.
XI 2.1: For event types TouchBegin, TouchUpdate, TouchUpdateUnowned, and
TouchEnd, the valuators are those specified as TouchAxisClass.
flags
Miscellaneous information about this event; the union of the
common flag set and either the key or pointer flag set,
@ -1526,6 +1793,20 @@ EVENTHEADER { type: BYTE
KeyRepeat means that this event is for repeating purposes, and
the physical state of the key has not changed. This is only
valid for KeyPress events.
PointerEmulated means that this event is an emulated pointer event
caused by a touch device. A client listening to touch events and pointer
events should ignore PointerEmulated events to avoid duplicate
processing. This is only valid for pointer events (MotionNotify,
ButtonPress, ButtonRelease).
TouchAccepted (for TouchEnd events only) means that the current owner
of the touch stream has “accepted” it, and this client will not receive
any further events from that touch sequence.
TouchPendingEnd (for touch events only) means that the touch
has physically ended, however another client still holds a grab, so the
touch should be considered alive until all grabbing clients have
accepted or passed on ownership. The touch will not generate any
further motion events once an event with TouchPendingEnd has been
received.
Modifier state in mods is detailed as follows:
base_mods
@ -1543,6 +1824,30 @@ EVENTHEADER { type: BYTE
locked_group
XKB locked group state.
XI 2.1:
A TouchBegin event is generated whenever a new touch sequence initializes
A TouchEnd event is generated whenever a touch sequence ceases. A
TouchUpdate event is generated whenever a touch axis valuator value
changes, or a flag (e.g. pending end) has changed for that touch sequence;
this may result in a TouchUpdate event being sent with zero valuators. A
TouchOwnership event is sent when a client becomes the owner of a touch.
The average finger size is significantly larger than one pixel. The
selection of the hotspot of a touchpoint is implementation dependent and
may not be the logical center of the touch.
Touch tracking IDs are provided in the detail field of touch events. Its
value is always provided in every touch event. Tracking IDs are
represented as unsigned 32-bit values and increase in value for each new
touch, wrapping back to 0 upon reaching the numerical limit of IDs.
Touch events do not generate enter/leave events, and are not affected by
other grabs (including device freezing), although any pointer events
generated by emulation will still be subject to all the same constraints
as normal pointer events, including enter/leave events, and being affected
by frozen devices.
┌───
RawEvent
EVENTHEADER
@ -1673,5 +1978,107 @@ EVENTHEADER { type: BYTE
what
Specifies what has been changed.
XI 2.1:
┌───
TouchOwnershipEvent (since XI 2.1):
EVENTHEADER
sourceid: DEVICEID
touchid: CARD32
flags: SETofTOUCHOWNERSHIPFLAGS
└───
TOUCHOWNERSHIPFLAGS: (none currently defined)
A TouchOwnershipEvent indicates that ownership has changed, and the client
is now the owner of the touch sequence specified by touchid.
sourceid
The source device that originally generated the event.
touchid
The identifier of the touch sequence.
flags
A bitmask of flags for this event.
❧❧❧❧❧❧❧❧❧❧❧
Appendix A: XI 2.1 Use-cases
All use-cases that include the receiving and processing of touch events
require the client to announce XI 2.1 support in the XIQueryVersion request.
∙ Client C wants to process touch events from a device D on window W.
⊳ C calls XISelectEvent for
XI_Touch{Begin|Update|UpdateUnowned|Ownership|End} from D on W.
⊳ C receives TouchBegin whenever a touch sequence starts within
W's borders.
⊳ C receives a TouchOwnership event indicating that it is now the owner
of the touch sequence.
⊳ C receives TouchUpdate events whenever a touch axis valuator value
changes for a touch sequence it received a TouchBegin event for.
⊳ C receives TouchEnd whenever a touch it received an TouchBegin event
for ceases.
∙ Client C wants to process touch events from a device D on window W, while
client I wants to pre-process these events.
⊳ C calls XISelectEvent for
XI_Touch{Begin|Update|UpdateUnowned|Ownership|End} from D on W.
⊳ I calls XIPassiveGrab for
XI_Touch{Begin|Update|UpdateUnowned|Ownership|End} from D on a parent
window of W.
⊳ I receives TouchBegin whenever a touch begins within window W, as well
as a TouchOwnership event indicating that it currently owns the touch
sequence. C receives a TouchBegin event as well, but without
TouchOwnership.
⊳ When a touch axis valuator changes in this touch sequence, I receives a
TouchUpdate event, while C receives a TouchUpdateUnowned event. I may
process the events to determine if it is going to claim or reject the
touch, whereas C may perform reversible processing.
⊳ If I decides it is going to claim the event for its exclusive
processing, it calls XIAllowTouchEvents with the XITouchOwnerAccept flag
set; at this point, C receives a TouchEnd event with the
TouchAccepted flag set, and undoes any processing it may have done
on the touch sequence. Further TouchUpdate events are delivered only
to I.
⊳ Alternately, if I decides it does not want to receive further events from
this touch sequence, it calls XIAllowTouchEvents with the
XITouchOwnerReject flag set; at this point, I receives a TouchEnd event
confirming that it has rejected the touch. C receives a TouchOwnership
event confirming that it is now the new owner of the touch, and further
TouchUpdate events are delivered only to C. As C now owns the touch,
it is free to perform irreversible processing of the sequence.
⊳ When the touch physically ceases, a TouchEnd event is sent to all
clients still receiving TouchUpdate events.
∙ Client C wants to process touch events from a device D on window W, while
client I wants to process pointer events on window Y, which is W's parent.
⊳ I calls XIPassiveGrab for XI_{ButtonPress,MotionNotify,ButtonRelease}
from D on Y.
⊳ C calls XISelectEvent for
XI_Touch{Begin|Update|UpdateUnowned|Ownership|End} from D on W.
⊳ I receives a ButtonPress event whenever a touch begins within W, and is
considered the owner of the event. C receives a TouchBegin event, but
does not receive a TouchOwnership event.
⊳ When the touchpoint moves, I will receive a MotionNotify event, and C
will receive a TouchUpdateUnowned event. Event delivery to I will be
subject to the standard delivery mechanism (including being queued if
the device is frozen, et al), while C receives events as soon as they
are processed by the server.
⊳ I may assert ownership by calling XIAllowEvents on Y with AsyncDevice,
which will cause all further events to be sent only to I, with a
TouchEnd event being sent to C.
⊳ Alternately, I may assert disinterest by calling XIAllowEvents on Y
with ReplayDevice, which will cause no further events from that touch
to be sent to I, and a TouchOwnership event to be sent to C, with
subsequent motion events being sent as TouchMotion.
∙ Driver DRV provides touch support from tracked device D:
⊳ DRV initializes a TouchClass for the device and a TouchAxisClass for
each axis available on the device.
⊳ DRV parses D's device protocol and selects one touch sequence to be
emulated as pointer event.
⊳ DRV calls the respective input driver API with the touch sequence
data. The touch sequence emulating a pointer has the respective flag
set. DRV does not submit pointer data for any touchpoint.

2
configure.ac
View file

@ -1,5 +1,5 @@
AC_PREREQ([2.60])
AC_INIT([InputProto], [2.0.1], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AC_INIT([InputProto], [2.0.99.1], [https://bugs.freedesktop.org/enter_bug.cgi?product=xorg])
AM_INIT_AUTOMAKE([foreign dist-bzip2])
AM_MAINTAINER_MODE