diff options
| -rw-r--r-- | XI2.h | 11 | ||||
| -rw-r--r-- | XI2proto.h | 49 | ||||
| -rw-r--r-- | specs/XI2proto.txt | 188 |
3 files changed, 246 insertions, 2 deletions
@@ -160,6 +160,11 @@ #define XITouchPendingEnd (1 << 16) #define XITouchEmulatingPointer (1 << 17) +/* Barrier event flags */ +#define XIBarrierPointerReleased (1 << 0) +#define XIBarrierDeviceIsGrabbed (1 << 1) + + /* Touch modes */ #define XIDirectTouch 1 #define XIDependentTouch 2 @@ -199,7 +204,9 @@ #define XI_RawTouchBegin 22 #define XI_RawTouchUpdate 23 #define XI_RawTouchEnd 24 -#define XI_LASTEVENT XI_RawTouchEnd +#define XI_BarrierHit 25 /* XI 2.3 */ +#define XI_BarrierLeave 26 +#define XI_LASTEVENT XI_BarrierLeave /* 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. */ @@ -232,5 +239,7 @@ #define XI_RawTouchBeginMask (1 << XI_RawTouchBegin) #define XI_RawTouchEndMask (1 << XI_RawTouchEnd) #define XI_RawTouchUpdateMask (1 << XI_RawTouchUpdate) +#define XI_BarrierHitMask (1 << XI_BarrierHit) +#define XI_BarrierLeaveMask (1 << XI_BarrierLeave) #endif /* _XI2_H_ */ @@ -67,6 +67,7 @@ #define Time uint32_t #define Atom uint32_t #define Cursor uint32_t +#define Barrier uint32_t /** * XI2 Request opcodes @@ -92,9 +93,10 @@ #define X_XIDeleteProperty 58 #define X_XIGetProperty 59 #define X_XIGetSelectedEvents 60 +#define X_XIBarrierReleasePointer 61 /** Number of XI requests */ -#define XI2REQUESTS (X_XIGetSelectedEvents - X_XIQueryPointer + 1) +#define XI2REQUESTS (X_XIBarrierReleasePointer - X_XIQueryPointer + 1) /** Number of XI2 events */ #define XI2EVENTS (XI_LASTEVENT + 1) @@ -815,6 +817,22 @@ typedef struct { } xXIGetPropertyReply; #define sz_xXIGetPropertyReply 32 +typedef struct { + uint16_t deviceid; + uint16_t pad; + Barrier barrier; + uint32_t eventid; +} xXIBarrierReleasePointerInfo; + +typedef struct { + uint8_t reqType; /**< Input extension major opcode */ + uint8_t ReqType; /**< Always X_XIBarrierReleasePointer */ + uint16_t length; + uint32_t num_barriers; + /* array of xXIBarrierReleasePointerInfo */ +} xXIBarrierReleasePointerReq; +#define sz_xXIBarrierReleasePointerReq 8 + /************************************************************************************* * * * EVENTS * @@ -1035,10 +1053,39 @@ typedef struct uint32_t pad3; } xXIPropertyEvent; +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_BarrierHit or ::XI_BarrierLeave */ + uint16_t deviceid; + Time time; + uint32_t eventid; + Window root; + Window event; + Barrier barrier; +/* └──────── 32 byte boundary ────────┘ */ + uint32_t dtime; + uint32_t flags; /**< ::XIBarrierPointerReleased + ::XIBarrierDeviceIsGrabbed */ + uint16_t sourceid; + int16_t pad; + FP1616 root_x; + FP1616 root_y; + FP3232 dx; + FP3232 dy; +} xXIBarrierEvent; + +typedef xXIBarrierEvent xXIBarrierHitEvent; +typedef xXIBarrierEvent xXIBarrierPointerReleasedEvent; +typedef xXIBarrierEvent xXIBarrierLeaveEvent; #undef Window #undef Time #undef Atom #undef Cursor +#undef Barrier #endif /* _XI2PROTO_H_ */ diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt index c018026..b1c29c0 100644 --- a/specs/XI2proto.txt +++ b/specs/XI2proto.txt @@ -14,6 +14,7 @@ Authors: History ------- +- v2.3, December 2012: Pointer barrier events added - v2.2, March 2012: Multitouch support added - v2.1, December 2011: new raw event behaviour, smooth scrolling support added @@ -57,6 +58,10 @@ Changes in version 2.2 - Multitouch support added +Changes in version 2.3 +---------------------- + +- Pointer barrier events added // ❧❧❧❧❧❧❧❧❧❧❧ @@ -551,6 +556,54 @@ window set has been reached, the event is delivered: Emulated pointer events will have the PointerEmulated flag set. A touch event that emulates pointer events has the TouchEmulatingPointer flag set. + +[[barrier-events]] +Pointer barrier events +^^^^^^^^^^^^^^^^^^^^^^ +If a master pointer moves against a pointer barrier blocking movement in +that pointer's direction, the movement of the pointer is clamped to the x or +y coordinate of the barrier, whichever applies. For a description of pointer +barriers and barrier creation and destruction see the XFixes protocol +specification v 5.0 or later. +http://cgit.freedesktop.org/xorg/proto/fixesproto/plain/fixesproto.txt + +A pointer hitting a blocking barrier creates a new barrier event sequence, +identified by a unique event ID. A new event ID is assigned when the pointer +first hits a barrier. Subsequent movements against or along the pointer +barrier are assigned the same event ID. The event generated by the pointer +leaving the barrier, or being released by a client request, is the last +event with this event ID. Any future movements of this device blocked by +this barrier will be assigned a new event ID. + +Pointer barrier events are delivered exclusively to the client that created +the barrier, and to the window specified in the CreatePointerBarrier +request (the "barrier window"). A pointer barrier blocks pointer movement +regardless of whether its window is mapped and/or viewable. If the pointer +barrier window is destroyed, the pointer barrier remains blocking but a +client will not receive further events. + +If a device is actively grabbed by a client or a passive grab activated +for this client, and the pointer moves against a pointer barrier created by +this client and the grab-window is the barrier window, that client will +receive pointer barrier events if: +- owner-events is true or false and the grab's event mask includes + pointer barrier events, or +- owner-events is true and the client has selected for barrier events on the + barrier window. + +If the grab-window is not the barrier window, the client will receive events +if: +- the client has selected for barrier events on the barrier window. + +If the barrier is not owned by this client, no barrier events are sent to +this client. The client owning the barrier will receive events if: +- the client has pointer barrier events selected on the window associated + with the pointer barrier + +The BarrierDeviceIsGrabbed flag is set whenever a pointer barrier event is +generated while the device is actively grabbed by any client or a passive +grab has activated for this device prior to the event. + [[glossary-notations]] Notations used in this document ------------------------------- @@ -1940,6 +1993,48 @@ giving the number of trailing unread bytes in the stored property. If delete is True and the bytes_after is zero, the property is also deleted from the device, and a XIPropertyNotify event is generated on the device. + +[[requests-xi23]] +Requests introduced in version 2.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[requests-barrierreleasepointer]] +XIBarrierReleasePointer +^^^^^^^^^^^^^^^^^^^^^^^ + ┌─── + XIBarrierReleasePointer + num_items: CARD32 + ▶ + data: LISTofBARRIERRELEASEINFO + └─── + + BARRIERRELEASEINFO { deviceid: DEVICEID, + barrier: Barrier, + eventid: CARD32 } + +Release a pointer currently blocked by a barrier. In the future, movement of +this pointer against the barrier will not be blocked. + + deviceid + The device currently being blocked by a barrier + barrier + The barrier currently blocking the device + eventid + The unique event ID assigned to this barrier event sequence + +If the barrier given does not currently block this device, or the eventid +is invalid, this request does nothing. + +Releasing a pointer barrier is only valid during one barrier event sequence, +and only applies to the next movement of this device against this barrier. +If the pointer moves away from the barrier following a +XIBarrierReleasePointer request, the release request is discarded. In the +future, if the pointer moves against the barrier again, a new eventid is +assigned and the client must re-issue the XIBarrierReleasePointer request. + +If the device is not a master pointer device, a BadDevice error results. +If the barrier does not name a valid barrier, a BadValue error results. + [[events]] Events @@ -1984,6 +2079,11 @@ Version 2.2: - RawTouchUpdate - RawTouchEnd +Version 2.3: + + - BarrierHit + - BarrierLeave + All events have a set of common fields specified as EVENTHEADER. @@ -2434,6 +2534,94 @@ is now the owner of the touch sequence specified by touchid. flags A bitmask of flags for this event. +[[events-xi23]] +Events introduced in version 2.3 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +[[events-barrierevent]] +BarrierEvent +^^^^^^^^^^^^ + ┌─── + BarrierEvent + EVENTHEADER + eventid: CARD32 + root: Window + event: Window + barrier: Barrier + dtime: CARD32 + flags: SETofBARRIERFLAGS + sourceid: DEVICEID + root_x: FP1616 + root_y: FP1616 + dx: FP3232 + dy: FP3232 + └─── + + BARRIERFLAGS { PointerReleased, DeviceIsGrabbed } + +A BarrierEvent indicates interaction between a barrier and a pointer device. +If the event type is BarrierHit, pointer movement has been blocked by a +barrier. If the event type is BarrierLeave, a pointer previously blocked +by a barrier has moved away from that barrier, or has moved +through the blocking barrier following an earlier XIBarrierReleasePointer +request. + + eventid + The unique event ID for this barrier event sequence. + root + event + The root window or barrier window, respectively. The barrier window + is always the drawable specified in in the CreatePointerBarrier request. + barrier + The barrier blocking pointer movement. + dtime + The relative time in milliseconds between the last event and this + event. + flags + A set of flags that apply to this barrier event + PointerReleased: + The pointer has moved through the barrier following a + XIBarrierReleasePointer request (BarrierLeave only). + DeviceIsGrabbed: + The pointer device that generated this event is currently + grabbed. + sourceid + The source device that originally generated the event. + root_x + root_y + The position of the pointer in screen coordinates (16.16 fixed + point), after being constrained by barrier and/or screen extents. + dx + dy + The relative movement of the pointer from its previous position to + the new position if pointer movement were not constrained by this + barrier. + +Root coordinates in barrier events represent the position of the cursor +after confinement by barriers, screens and RandR output extents. + +Barrier event IDs are provided in the eventid field of barrier events. Its +value is always provided in every barrier event. Event IDs are +represented as unsigned 32-bit values and increase strictly monotonically in +value for each new barrier event sequence, wrapping back to 0 upon reaching +the numerical limit of IDs. The increment between two event IDs is +indeterminate. Clients may not assume that any future barrier constraints +will have specific event IDs. IDs are unique per device per barrier. + +If a pointer is actively grabbed after a barrier event sequence has +initiated, future barrier events of this sequence continue to use the same +eventid, but all barrier events have the DeviceIsGrabbed flag set. If the +pointer is ungrabbed, future events of this sequence have the same eventid +and the DeviceIsGrabbed flag is unset. + +The PointerReleased flag may only be set on a BarrierLeave event. +A BarrierLeave(PointerReleased) event is generated when the pointer moves +through the barrier following a XIBarrierReleasePointer request. The time +between the XIBarrierReleasePointer and the BarrierLeave event thus depends +on user input. +A BarrierLeave(PointerReleased) event is also generated if the barrier is +destroyed while pointer movement is constrained by the barrier. This event +has a dx/dy of 0/0. :numbered!: [[xi22-usecases]] |