[PATCH weston 1/3] Introduce pointer lock interface

[Bill Spitzak]

In any case this all sounds excessively complicated. I think this will work:

- Client can create a pointer_lock object from an wl_pointer. This takes 
a serial of an event so the compositor can decide whether it should be 
allowed by the event.

- Motion and push/release events still come in IDENTICAL to how they 
were before, except it acts as though the surface is infinite in size. 
This is to make it easier for toolkits to handle. There is no need for 
relative events as it is trivial for the toolkit to subtract the 
starting position. Acceleration should be unchanged.

- The client will only get an enter event if it has gotten a leave event 
before pointer lock is granted (this is probably impossible on most 
compositors). There is no difference between this enter event and a 
normal one.

- I don't think the client will get a leave event until pointer lock is 
cancelled, and only if the cursor ends up outside the surface.

- Tablets may change to a relative mode.

- The cursor stops moving. A new api is added (maybe to the pointer_lock 
object) that allows the cursor to be positioned. The coordinate system 
is exactly the same one the mouse events are using.

- The client can change the cursor image (including making it invisible) 
using the same api as always.

- The client cancels pointer lock by destroying the pointer lock object. 
Depending on the hardware this will either make the pointer move to the 
last cursor position, or move the cursor to the absolute pointer 
position. Either of these may cause leave, enter, and move events.

- The compositor can break pointer lock by sending a special event. This 
may be the only event that the pointer_lock object can produce. When the 
client gets it it should destroy the pointer lock object. I don't think 
it should be called "leave" and it has nothing to do with enter/leave.

Examples:

Game where pointer position controls things: client requests pointer 
lock on activation, and possibly on enter events. A smarter client can 
wait until the mouse hovers a bit before grabbing it. Client then hides 
the cursor and uses the relative events until the game ends or pointer 
lock is lost.

Restrict motion to the surface: client acts like the game, but does not 
hide the cursor. Instead on all motion it clamps the motion to the 
allowed area and places the cursor there, and acts like the motion is to 
that point.

"Slow scrollbar": on push client requests pointer lock. It then scales 
down the motion, moving it's scrollbar and the cursor the same so they 
still look locked together. On release it destroys the pointer lock.

Eyedropper color picker: client requests pointer lock after user enters 
color picker mode. It then moves the cursor to match the pointer 
position. On push/release it uses a privledged api to pick the color off 
the screen at that location. Depending on the app it may drop pointer 
lock at this point, or stay in color picker mode.

Tumble 3D controller: Client requests pointer lock on push of the shift 
key and destroys it on release of the shift key. It probably hides the 
cursor. It then computes tumble on all movements while the mouse is down.