[PATCH inputproto] Add pointer barrier events
Peter Hutterer
peter.hutterer at who-t.net
Thu Dec 6 22:25:05 PST 2012
New events:
XI_BarrierHit ... when a pointer moves against or along a barrier
XI_BarrierLeave . when a pointer moves away from or through a barrier
New requests:
XIBarrierReleasePointer ... allow movement through the barrier for the
next event
Co-authored-by: Jasper St. Pierre <jstpierre at mecheye.net>
Co-authored-by: Christopher James Halse Rogers <christopher.halse.rogers at canonical.com>
Signed-off-by: Peter Hutterer <peter.hutterer at who-t.net>
---
XI2.h | 11 +++-
XI2proto.h | 49 +++++++++++++-
specs/XI2proto.txt | 187 +++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 245 insertions(+), 2 deletions(-)
diff --git a/XI2.h b/XI2.h
index e864b06..5a245e8 100644
--- a/XI2.h
+++ b/XI2.h
@@ -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_ */
diff --git a/XI2proto.h b/XI2proto.h
index 9418357..4cdaa0d 100644
--- a/XI2proto.h
+++ b/XI2proto.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..402210f 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,93 @@ 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.
:numbered!:
[[xi22-usecases]]
--
1.7.11.7
More information about the xorg-devel
mailing list