Ubuntu Wiki

A gesture is a defined set of particular movements of pointing devices. GEIS provides no interpretation of gestures, only recognition and propagation.

Because gestures can be defined to have global meaning as well as local meaning, it makes sense that gesture recognition be provided by the system rather than be included as a library by a particular application or toolkit. This allows, for example, a set of gestures to be defined for the window manager in use on a display to receive gesture events even when another application is in the foreground and receiving the input.

GeisBoolean is an integral type representing a boolean value and should only hold the values GEIS_TRUE (1) and GEIS_FALSE (0).

GeisInt is an integral type large enough to hold any integral gesture attribute value which may be represented on the native platform. This may includes bitmasks, enumerants, integers, handles, and so forth.

GeisFloat is a floating-point type which can represent floating-point valued gesture attributes,

GeisString is a C-style zero-terminated string of characters in some character set. A GeisString is a read-only string and does not have to be freed or disposed of by the caller.

An application may need to support different sets of gestures from different input devices or associated with different regions of the same device. For this reason, GEIS provides for one or more distinct connections to the underlying gesture engine. The instances are distinguished by a GeisInstance object. All gesture types and gesture instances IDs are in a namespace associated with the GeisInstance and are not guaranteed to be system wide unique.

	This section is not complete.

GEIS functions usually return a status code indicating success or failure. The status codes that may be returned, and their meanings, are as follows.

	This section is not complete.

A GEIS instance may be initialized by calling

GeisStatus geis_init(GeisWinInfo *win_info, GeisInstance *geis_instance);

GEIS_SUCCESS is returned on success and geis_instance is updated with an instance value to be used in subsequent GEIS calls.

The definition of the GeisWinInfo fields is entirely dependant on the implementation. For example, an X11-based gesture recognizer may specify the window_id as the win_info argument.

A particular GEIS implementation may support a subset of standard configuarable items and, in addition, zero or more implementation-specific configuration items. The implementation-specific configuration items will be documented by the implementation.

To determine of a confiuration item is supported, use the following call.

GeisStatus geis_configuration_supported(GeisInstance instance,
                                        int          configuration_item);

This function will return GEIS_STATUS_SUCCESS if the configuration_item is supported by the implementation, GEIS_STATUS_NOT_SUPPORTED otherwise.

The following standard configuration items must be available. .Input Standard Configuration Items

Configuration-specifc values may be set and retrieved using the following calls.

GeisStatus geis_configuration_get_value(GeisInstance instance,
                                        int          configuration_item,
                                        void*        value);

GeisStatus geis_configuration_set_value(GeisInstance instance,
                                        int          configuration_item,
                                        void*        value);

The actual type and meaning of the value argument depends on the configuration_item. Standard configuration item types are described in the following table.

Integration with the native event loop is through an implementation-specific mechanism (likely obtained through the configuration calls above, but documented more thoroughly in the implementation documentation) combined with a call to the GEIS dispatch mechanism.

GeisStatus geis_event_dispatch(geisInstance instance);

Gestures are associated with input devices (a gesture must be input on a device). Client software may subscribe to gestures that occur on all input devices or on only a subset of input devices. For that to be possible, the client needs to enumerate all available input devices. In addition, many input devices have a dynamic lifetime — they may be added or removed asynchronously. the client software needs to be made aware that new input devices have become available or existing devices have become unavailable.

GEIS input device enumeration and availability notification is performed through the following interface.

typedef unsigned int GeisInputDeviceId;

#define GEIS_ALL_INPUT_DEVICES ((GeisInputDeviceId)0)

typedef void (*GeisInputCallback)(void             *cookie,
                                  GeisInputDeviceId device_id,
                                  void             *attrs);

typedef struct GeisInputFuncs
{
  GeisInputCallback  added;   /**< Receives new input device notices */
  GeisInputCallback  changed; /**< Receives modified input device notices */
  GeisInputCallback  removed; /**< Receives removes input device notices */

} GeisInputFuncs;

GeisStatus geis_input_devices(GeisInstance    geis_instance,
                              GeisInputFuncs  funcs,
                              void           *cookie);

The API provides a list of available input devices one at a time through the client-supplied added callback function.

The changed callback function or the removed callback function may be invoked at any time after geis_input_devices is called and before geis_finish is called to tear down the GeisInstance or geis_input_devices is called again to replace the callback function. This can occur when input devices are, for example, physically connected to or disconnected from the system.

The cookie value passed to geis_input_devices is passed unmodified to callback function. Client programs may use this for passing context-specific information into the callback.

The suggested behaviour of an implementation is to invoke the callback for each input device known at call time before returning from the geis_input_devices call.

Gestures are specific to a GeisInstance and set of input devices. The GeisInstance must be informed of the set of gestures (and input devices) of interest.

typedef unsigned int GeisGestureType;
typedef unsigned int GeisGestureId;

#define GEIS_ALL_GESTURES ((GeisGestureType)0)
#define GEIS_NO_GESTURE_ID ((GeisGestureId)0)

typedef void (*GeisGestureCallback)(void             *cookie,
                                    GeisGestureType   gesture_type,
                                    GeisGestureId     gesture_id,
                                    GeisSize          attr_count,
                                    GeisGestureAttr  *attrs);

typedef struct GeisGestureFuncs
{
  GeisGestureCallback  added;
  GeisGestureCallback  removed;
  GeisGestureCallback  start;
  GeisGestureCallback  update;
  GeisGestureCallback  finish;
} GeisGestureFuncs;

GeisStatus geis_subscribe(GeisInstance        geis_instance,
                          GeisInputDeviceId  *input_list,
                          const char*        *gesture_list,
                          GeisGestureFuncs    funcs,
                          void               *cookie);

GeisStatus geis_unsubscribe(GeisInstance     geis_instance,
                            GeisGestureType *gesture_list);

The client supplies a list of input devices (or the constant GEIS_ALL_INPUT_DEVICES) and a NULL terminated list of C-style strings naming the gestures to be recognized. The constant GEIS_ALL_GESTURES indicates all available gestures should be detected.

GEIS provides a list of gestures available in the desired window and input device(s) one at a time through the client-supplied added callback function with the GEIS_GESTURE_TYPE_ADDED action. This allows the client to build a map of gesture names to GeisGestureType. If the recognition engine does not support a named gesture type passed to geis_subscribe then no GeisGestureType is passed to the callback function for the named gesture.

The cookie value passed to geis_subscribe is passed unmodified to callback. Client programs may use this for passing context-specific information into the callback.

One of the gesture event callback functions may be invoked at any time after geis_input_devices is called and before geis_finish is called to tear down the GeisInstance or geis_input_devices is called again to replace the callback function. This can occur when input devices are, for example, physically connected to or disconnected from the system.

Most gestures will result in a start callback, zero or more update callbacks, and a finish callback. Some gestures such as tap gestures may result in only a single update callback. This behaviour is dependent on the underlying gesture recognition engine

Once a gesture is recognized, a GEIS_GESTURE_STARTED action is sent. A set of zero or more attributes will be returned. These attributes are specific to the gesture. Depending on the nature of the gesture, one or more GEIS_GESTURE_UPDATED actions may be sent, and finally a GEIS_GESTURE_FINISHED action will be sent. Each of these may or may not have a set of attributes associated.

A gesture or gesture type action is often associated with a set of attributes. These attributes are delivered to the callback function as a read-only array of GeisGestureAttr type, defined below.

typedef struct GeisGestureAttr
{
  GeisString   name;
  GeisAttrType type;
  union
  {
    GeisBoolean boolean_val;
    GeisFloat   float_val;
    GeisInteger integer_val;
    GeisString  string_val;
  };
} GeisGestureAttr;

Teardown of the gesture recognition session is accomplished by the geis_finish function.

GeisStatus geis_finish(GeisInstance *geis_instance);

This function frees any allocated resources associated with geis_instance. It does not affect other instances.

All resources are expected to be freed automatically on process termination. The geis_finish function is not expected to return any status value other than GEIS_SUCCESS.

All standard gestures provide a common set of attributes.

The GEIS specification defines an ISO C language binding. The GEIS header file <geis/geis.h> provides prototypes for all GEIS entry points and C preprocessors for all GEIS tokens, for use both by client code and implementers.

Languages other than C and C++ will define GEIS interfaces using other methods outside the scope of this specification.

To allow code to be written portably against future GEIS versions, the compile-time environment must make it possible to determine which GEIS version interface are available. For C and C++ code the <geis/geis.h> header defined C preprocessor symbols corresponding to all versions of GEIS supported by the implementation.

#define GEIS_VERSION_1_0  1

Future versions of GEIS will define additional preprocessor symbols corresponding to the major and minor numbers of those versions.

Constants and enumerator values for GEIS tokens defined in this specification are required to be common across all implementations. A reference version of the geis.h header file can be downloaded from to be determined.

All implementation-specific types, values, and macros used in geis.h are partitioned into an implementation header, geisimpl.h, which is automatically6 included by geis.h. Implementers should need only modify geisimpl.h, never geis.h.