[PATCH] fixesproto v6: Pointer barrier thresholds

[christopher.halse.rogers at canonical.com]

From: Christopher James Halse Rogers <christopher.halse.rogers at canonical.com>

---

This is prompted by a request from the Ubuntu DX team to conditionally restrict
pointer motion at a screen edge.  The Unity launcher appears on a screen edge,
triggered by pointer proximity, and the objective is to have a form of edge
resistance so that it is easy to summon the launcher on the border of two
displays while still allowing determined pointer motion through.

There doesn't seem to be a good way to implement this client-side.  Pointer
barriers seem the obvious mechanism, but turning them on and off runs
into roundtrip latency, and there's some useful information that the server
has that's not easily available to a client.

This is the second go at a protocol.  The first simply added a velocity-gated
pointer barrier request.  In testing this suboptimal behaviour - getting the
pointer past the barrier required too vigourous a motion, and it was desired
that the barrier would also respond to a period of gentler motion in addition
to being transparent to sufficiently fast movement.

I'm aware that this is becoming a bit elaborate.  I'd like some guidance -
I don't want to make something that's pointlessly generic, but it should be
useful outside of Unity's specific usecase.

 fixesproto.txt |  118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 118 insertions(+), 0 deletions(-)

diff --git a/fixesproto.txt b/fixesproto.txt
index 5903ac9..16a7aae 100644
--- a/fixesproto.txt
+++ b/fixesproto.txt
@@ -650,6 +650,124 @@ DestroyPointerBarrier
 
 	Errors: Barrier 
 
+************* XFIXES VERSION 6 OR BETTER ***********
+
+13. Pointer Barriers Expansion
+
+This update extends pointer barriers to optionally allow the pointer through
+when a threshold is reached.  This can be useful for desktop environments that
+wish to use a large region of the screen, such as an entire edge, to provide a
+casual target while allowing determined movement to pass through.
+
+13.1 Types
+
+	BarrierThreshold:		XID
+	BarrierThresholdKind:		{None, Distance, Velocity, HitCount}
+	BarrierEvent:			{Hit, ThresholdExceeded}
+
+13.2 Errors
+
+	BarrierThreshold
+
+13.3 Events
+
+BarrierNotify
+
+		subtype:		BarrierEvent
+		window:			WINDOW
+		timestamp:		Timestamp
+		barrier:		BARRIER
+		threshold:		BARRIERTHRESHOLD or None
+		value:			CARD32
+		x, y:			INT16
+
+13.4 Requests
+
+SelectBarrierInput
+
+		window:			WINDOW
+		event-mask:		SETofBarrierEvent
+
+
+	This request directs barrier events to the named window.  Subtype
+	indicates the trigger of the event, which is Hit when the barrier has
+	prevented pointer movement and ThresholdExceeded when the barrier has
+	been hit but has not prevented pointer movement due to the threshold
+	being exceeded.
+	
+	Barrier is the barrier on which the event was triggered, which is
+	associated with threshold or None if no threshold is associated.
+	If threshold is not None, value contains the current value of the
+	property the threshold measures against.
+	
+	(x,y) contain the coordinates of the pointer after restriction by any
+	applicable barriers.
+
+	In the case of multiple overlapping barriers an event is sent for each.
+
+CreateBarrierThreshold
+
+		threshold:		BARRIERTHRESHOLD
+		type:			BarrierThresholdKind
+		value:			CARD32
+
+	This request creates a new barrier threshold.	This threshold
+	specifies a condition under which a pointer barrier will allow a
+	pointer to pass through unimpeded.
+
+	Type can be None, in which case the threshold is never triggered.
+
+	Type can be Distance, in which case the threshold will trigger if the
+	user attempts to move the pointer a cumulative distance in px greater
+	than value.  The distance is not automatically reset, so once the
+	threshold has been triggered it will remain triggered.
+
+	Type can be Velocity, in which case the threshold will trigger if the 
+	instantaneous velocity of the pointer, perpendicular to the barrier,
+	in px/sec is greater than value.
+
+	Type can be HitCount, in which case the threshold will trigger once the
+	barrier has been hit value times.  The count is not automatically
+	reset, so once the threshold has been triggered it will	remain
+	triggered.
+
+	If type is not one of these values, BadValue is generated.
+
+	Errors: IDChoice, Value
+
+AddBarrierThresholdOr
+AddBarrierThresholdAnd
+
+		threshold:		BARRIERTHRESHOLD
+		type:			BarrierThresholdKind
+		value:			CARD32
+
+	Add an additional constraint to threshold.
+
+ResetBarrierThreshold
+
+		threshold:		BARRIERTHRESHOLD
+
+	Resets threshold to the ground state.  This is necessary for
+	thresholds of type Distance and HitCount, which have an associated
+	state.  It has no effect on thresholds of type None or Velocity.
+
+AssignPointerBarrierThreshold
+
+		barrier:		BARRIER
+		threshold:		BARRIERTHRESHOLD
+
+	Assigns threshold to barrier.  The barrier will only block pointer
+	motion while threshold is untriggered.
+
+DestroyBarrierThreshold
+
+		threshold:		BARRIERTHRESHOLD
+
+	Destroys the named threshold.
+
+	Errors: BarrierThreshold
+
 99. Future compatibility
 
 This extension is not expected to remain fixed.  Future changes will
-- 
1.7.8.3