diff options
Diffstat (limited to 'specs/XI2proto.txt')
| -rw-r--r-- | specs/XI2proto.txt | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/specs/XI2proto.txt b/specs/XI2proto.txt index c018026..d30fcca 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,95 @@ 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, or the +master pointer blocked by the barrier is removed. This event +has a dx/dy of 0/0. :numbered!: [[xi22-usecases]] |