X Gesture Extension protocol - draft proposal v1

[Chase Douglas]

On Mon, 2010-08-16 at 19:27 +0300, Tiago Vignatti wrote:
> On Mon, Aug 16, 2010 at 05:13:20PM +0200, ext Chase Douglas wrote:
> > 
> >                             The X Gesture Extension
> >                                   Version 1.0
> > 
> >                                  Chase Douglas
> >                           chase.douglas at canonical.com
> >                                 Canonical, Ltd.
> > 
> > ********************************************************************************
> > ********************************************************************************
> > **************************                           ***************************
> > **************************    DRAFT PROPOSAL (v1)    ***************************
> > **************************                           ***************************
> > ********************************************************************************
> > ********************************************************************************
> > 
> > 
> > 1. Introduction
> > 
> > The X Gesture Extension is a mechanism to provide the following:
> > - Interface for X clients to register and receive gesture primitive events
> > - Interface for an X client to act as a gesture engine
> > 
> > Gestures may be seen as logical groupings of multitouch input events. Thus,
> > this extension is dependent on the X Input Extension version 2.1, which
> > implements multitouch input support.
> > 
> >                               ❧❧❧❧❧❧❧❧❧❧❧
> > 
> > 2. Notations used in this document
> > 
> > Notation for requests:
> > ┌───
> >     Name of request
> >         name of request field:       type of request field
> >         name of request field:       type of request field
> >         ▶
> >         name of reply field:         type of reply field
> > └───
> > 
> > Notation for events:
> > ┌───
> >     Name of event
> >         name of field:               type of field
> >         name of field:               type of field
> > └───
> > 
> > Complex fields are specified in the following notation:
> >           name of field:                  COMPLEXFIELDTYPE
> > or, if multiple of these fields exist:
> >           name of field:                  LISTofCOMPLEXFIELDTYPE
> > 
> > COMPLEXFIELDTYPE:  { name of subfield:   type of subfield,
> >                      name of subfield:   type of subfield }
> > 
> >                               ❧❧❧❧❧❧❧❧❧❧❧
> > 3. Data types
> > 
> > DEVICE { DEVICEID, AllDevices }
> >         A DEVICE specifies either an X Input DEVICEID or AllDevices.
> > 
> > DEVICEID { CARD16 }
> >         A DEVICEID is a numerical ID for an X input device currently available
> >         in the server. The server may re-use a device ID after a device's
> >         removal. The device IDs 0 and 1 are reserved.
> >         AllDevices ........ 0
> > 
> > GESTUREID { CARD16 }
> >         A GESTUREID is a numerical ID for an X Gesture type currently available
> >         in the server. The server may re-use a gesture ID if available gesture
> >         types change.
> > 
> > GESTUREFLAG { MUTEX }
> >         A flag telling the server to not propagate gestures to child clients
> >         when a gesture type in the associated mask is set. The gesture will only
> >         be sent to the registering client.
> >         When registering for gestures, a client using this flag may not listen
> >         for gesture IDs that any other client has registered for with the MUTEX
> >         flag.
> > 
> > GESTUREMASK
> >         A GESTUREMASK is a binary mask defined as (1 << gesture ID). A
> >         SETofGESTUREMASK is a binary OR of zero or more GESTUREMASK.
> > 
> > GESTUREPROP { property:             ATOM
> >               property_type:        ATOM }
> >         A GESTUREPROP is the definition of a single property of a gesture. The
> >         property field specifies a label for the gesture. The property_type
> >         field specifies the data type of the property. For example, the property
> >         type may be the atom representing "FLOAT" for an IEEE 754 32-bit
> >         representation of a floating point number. Where applicable, both the
> >         property and the type should conform to the standard gesture
> >         definitions.
> > 
> > EVENTRANGE { start:                 CARD16
> >              end:                   CARD16 }
> >         An EVENTRANGE specifies a range of event sequence numbers, inclusively.
> > 
> >                               ❧❧❧❧❧❧❧❧❧❧❧
> > 3. Gesture Primitives and Events
> > 
> > The XInput protocol through version 2.0 supports single touch input devices.
> > Beginning with version 2.1, XInput will support multitouch input devices. The
> > protocol extension provides a mechansim for selection and propagation of
> > multitouch events to windows they occur within. The selection and propagation
> > is performed per touch; if a user touches a parent window and a child window
> > with separate touches simultaneously, and both windows have input events
> > selected for, the touch events will be sent to their respective windows. This
> > functionality is useful for general multitouch events, but is ill-suited for
> > user interface paradigms that require groupings of touches to be interpreted as
> > a single unit.
> > 
> > The X Gesture extension aims to provide for selection and propagation of gesture
> > primitives. Gesture primitives can be best thought of as fundamental multitouch
> > input groupings that convey specific meaning. Gesture primitives comprise events
> > such as pans, pinches, and rotatation. Primitives are also defined by the number
>                              ^^^^^^^^^^
>                              typo

Thanks for pointing this out. I'm sure there are many more :).

I've started keeping the document on launchpad in a bzr repo:

http://bazaar.launchpad.net/~utouch-team/utouch/docs/annotate/head:/XGesture.txt

If people want this moved to cgit.freedesktop.org, that's fine with me.
I'll just need git access :).

> nitpicking: why call this work as a new extension? Should be inside Xi 2.1
> (which could be bumped maybe to 3) given the strict dependency and relation?

It very well could be, but I didn't want to propose such without
consulting with Peter first. I'm perfectly happy to roll it all together
if that's what's best.

> Anyway, the work looks promising. Congrats!

Thanks!

-- Chase