GEIS  2.0
Gesture Engine Interface Support

Modules

 Input Devices
 

Functions

void geis_event_delete (GeisEvent event)
 Destroys a GeisEvent. More...
 
GeisEventType geis_event_type (GeisEvent event)
 Gets the type of the event. More...
 
GeisSize geis_event_attr_count (GeisEvent event)
 Gets the number of attributes in the event. More...
 
GeisAttr geis_event_attr (GeisEvent event, GeisSize index)
 Gets an indicated attribute from the event. More...
 
GeisAttr geis_event_attr_by_name (GeisEvent event, GeisString attr_name)
 Gets a named attribute from the event. More...
 

Vendor-defined Configuration Items

These configuration items are not a part of the GEIS specification and may change.
GeisStatus geis_get_configuration (Geis geis, GeisString configuration_item_name, void *configuration_item_value)
 Gets a feature configuration value. More...
 
GeisStatus geis_set_configuration (Geis geis, GeisString configuration_item_name, void *configuration_item_value)
 Sets a feature configuration value. More...
 
GeisStatus geis_input_devices (GeisInstance geis_instance, GeisInputFuncs *func, void *cookie)
 Registers a callback to receive information on input devices. More...
 
GeisStatus geis_subscribe (GeisInstance geis_instance, GeisInputDeviceId *input_list, const char **gesture_list, GeisGestureFuncs *funcs, void *cookie)
 Registers a callback to receive gesture events. More...
 
GeisStatus geis_unsubscribe (GeisInstance geis_instance, GeisGestureType *gesture_list)
 Unsubscribes to one or more gestures. More...
 
GeisString geis_attr_name (GeisAttr attr)
 An opaque type that encapsulates a GEIS attribute. More...
 
GeisAttrType geis_attr_type (GeisAttr attr)
 Gets the type of an attribute value. More...
 
GeisBoolean geis_attr_value_to_boolean (GeisAttr attr)
 Gets the value of an attribute as a GeisBoolean. More...
 
GeisFloat geis_attr_value_to_float (GeisAttr attr)
 Gets the value of an attribute as a GeisFloat. More...
 
GeisInteger geis_attr_value_to_integer (GeisAttr attr)
 Gets the value of an attribute as a GeisInteger. More...
 
GeisPointer geis_attr_value_to_pointer (GeisAttr attr)
 Gets the value of an attribute as a GeisPointer. More...
 
GeisString geis_attr_value_to_string (GeisAttr attr)
 Gets the value of an attribute as a GeisString. More...
 
void geis_register_event_callback (Geis geis, GeisEventCallback event_callback, void *context)
 Registers an event-handler callback. More...
 
GeisStatus geis_dispatch_events (Geis geis)
 Pumps the GEIS event loop. More...
 
GeisStatus geis_next_event (Geis geis, GeisEvent *event)
 Retrieves the next queued GEIS event. More...
 
#define GEIS_CONFIG_MAX_EVENTS
 
#define GEIS_CONFIG_ATOMIC_GESTURES
 Indicates if atomic gestures are in use. More...
 
#define GEIS_CONFIG_SEND_TENTATIVE_EVENTS
 See GEIS_INIT_SEND_TENTATIVE_EVENTS. More...
 
#define GEIS_CONFIG_SEND_SYNCHRONOS_EVENTS
 See GEIS_INIT_SEND_SYNCHRONOS_EVENTS. More...
 
#define GEIS_CONFIG_DRAG_THRESHOLD
 Movement threshold for recognizing a DRAG gesture (in meters). More...
 
#define GEIS_CONFIG_DRAG_TIMEOUT
 Timeout for recognizing a DRAG gesture (in milliseconds). More...
 
#define GEIS_CONFIG_PINCH_THRESHOLD
 Movement threshold for recognizing a PINCH gesture (in meters). More...
 
#define GEIS_CONFIG_PINCH_TIMEOUT
 Timeout for recognizing a PINCH gesture (in milliseconds). More...
 
#define GEIS_CONFIG_ROTATE_THRESHOLD
 Movement threshold for recognizing a ROTATE gesture (in meters). More...
 
#define GEIS_CONFIG_ROTATE_TIMEOUT
 Timeout for recognizing a ROTATE gesture (in milliseconds). More...
 
#define GEIS_CONFIG_TAP_THRESHOLD
 Movement threshold for recognizing a TAP gesture (in meters). More...
 
#define GEIS_CONFIG_TAP_TIMEOUT
 Timeout for recognizing a TAP gesture (in milliseconds). More...
 
#define GEIS_CONFIG_NUM_ACTIVE_SUBSCRIPTIONS
 The number of subscriptions currently active in the back end. More...
 
#define GEIS_ALL_INPUT_DEVICES
 
#define GEIS_ALL_GESTURES
 Selects ALL input devices. More...
 
#define GEIS_NO_GESTURE_ID
 
#define GEIS_DEFAULT_EVENT_CALLBACK
 A special constant indicating the use of the default event callback. More...
 
enum  _GeisEventType {
  GEIS_EVENT_DEVICE_AVAILABLE , GEIS_EVENT_DEVICE_UNAVAILABLE , GEIS_EVENT_CLASS_AVAILABLE , GEIS_EVENT_CLASS_CHANGED ,
  GEIS_EVENT_CLASS_UNAVAILABLE , GEIS_EVENT_GESTURE_BEGIN , GEIS_EVENT_GESTURE_UPDATE , GEIS_EVENT_GESTURE_END ,
  GEIS_EVENT_TENTATIVE_BEGIN , GEIS_EVENT_TENTATIVE_UPDATE , GEIS_EVENT_TENTATIVE_END , GEIS_EVENT_INIT_COMPLETE ,
  GEIS_EVENT_USER_DEFINED , GEIS_EVENT_ERROR
}
 
typedef unsigned int GeisInputDeviceId
 
typedef void(* GeisInputCallback) (void *cookie, GeisInputDeviceId device_id, void *attrs)
 Prototype for input device callback functions. More...
 
typedef struct GeisInputFuncs GeisInputFuncs
 Callback functions used to handle changes in the available input devices. More...
 
typedef unsigned int GeisGestureType
 
typedef unsigned int GeisGestureId
 
typedef struct GeisGestureAttr GeisGestureAttr
 An individual gesture attribute. More...
 
typedef void(* GeisGestureCallback) (void *cookie, GeisGestureType gesture_type, GeisGestureId gesture_id, GeisSize attr_count, GeisGestureAttr *attrs)
 A callback used for different gesture events. More...
 
typedef struct GeisGestureFuncs GeisGestureFuncs
 The set of callback functions invoked for various gesture-related events. More...
 
typedef enum _GeisEventType GeisEventType
 
typedef void(* GeisEventCallback) (Geis geis, GeisEvent event, void *context)
 The application callback type for the event dispatcher. More...
 

Required Configuration Items

These configuration items are defined by the GEIS specification.
#define GEIS_CONFIGURATION_FD
 Gets a Unix file descriptor that will signal the availablility of GEIS events for processing. More...
 

Detailed Description

Macro Definition Documentation

◆ GEIS_ALL_GESTURES

#define GEIS_ALL_GESTURES

Selects ALL input devices.

◆ GEIS_CONFIG_ATOMIC_GESTURES

#define GEIS_CONFIG_ATOMIC_GESTURES

Indicates if atomic gestures are in use.

Value type GeisBoolean.

◆ GEIS_CONFIG_DRAG_THRESHOLD

#define GEIS_CONFIG_DRAG_THRESHOLD

Movement threshold for recognizing a DRAG gesture (in meters).

Value type GeisFloat.

◆ GEIS_CONFIG_DRAG_TIMEOUT

#define GEIS_CONFIG_DRAG_TIMEOUT

Timeout for recognizing a DRAG gesture (in milliseconds).

Value type GeisInteger.

◆ GEIS_CONFIG_NUM_ACTIVE_SUBSCRIPTIONS

#define GEIS_CONFIG_NUM_ACTIVE_SUBSCRIPTIONS

The number of subscriptions currently active in the back end.

This config is query-only and intended for unit test validations.

◆ GEIS_CONFIG_PINCH_THRESHOLD

#define GEIS_CONFIG_PINCH_THRESHOLD

Movement threshold for recognizing a PINCH gesture (in meters).

Value type GeisFloat.

◆ GEIS_CONFIG_PINCH_TIMEOUT

#define GEIS_CONFIG_PINCH_TIMEOUT

Timeout for recognizing a PINCH gesture (in milliseconds).

Value type GeisInteger.

◆ GEIS_CONFIG_ROTATE_THRESHOLD

#define GEIS_CONFIG_ROTATE_THRESHOLD

Movement threshold for recognizing a ROTATE gesture (in meters).

Value type GeisFloat.

◆ GEIS_CONFIG_ROTATE_TIMEOUT

#define GEIS_CONFIG_ROTATE_TIMEOUT

Timeout for recognizing a ROTATE gesture (in milliseconds).

Value type GeisInteger.

◆ GEIS_CONFIG_SEND_SYNCHRONOS_EVENTS

#define GEIS_CONFIG_SEND_SYNCHRONOS_EVENTS

See GEIS_INIT_SEND_SYNCHRONOS_EVENTS.

◆ GEIS_CONFIG_SEND_TENTATIVE_EVENTS

#define GEIS_CONFIG_SEND_TENTATIVE_EVENTS

See GEIS_INIT_SEND_TENTATIVE_EVENTS.

◆ GEIS_CONFIG_TAP_THRESHOLD

#define GEIS_CONFIG_TAP_THRESHOLD

Movement threshold for recognizing a TAP gesture (in meters).

Value type GeisFloat.

◆ GEIS_CONFIG_TAP_TIMEOUT

#define GEIS_CONFIG_TAP_TIMEOUT

Timeout for recognizing a TAP gesture (in milliseconds).

Value type GeisInteger.

◆ GEIS_CONFIGURATION_FD

#define GEIS_CONFIGURATION_FD

Gets a Unix file descriptor that will signal the availablility of GEIS events for processing.

Examples
geis2.c.

◆ GEIS_DEFAULT_EVENT_CALLBACK

#define GEIS_DEFAULT_EVENT_CALLBACK

A special constant indicating the use of the default event callback.

Typedef Documentation

◆ GeisEventCallback

typedef void(* GeisEventCallback) (Geis geis, GeisEvent event, void *context)

The application callback type for the event dispatcher.

Parameters
[in]geisthe GEIS API instance
[in]eventthe opaque event pointer
[in]contextthe application-supplied context value

◆ GeisGestureAttr

An individual gesture attribute.

Gesture events are associated with a list of attributes, each of which is a (name, type, value) tuple. These attribute reveal a little piece of information about a gesture.

◆ GeisGestureCallback

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

A callback used for different gesture events.

Parameters
[in]cookiean application-specific value to be passed to the callback.
[in]gesture_typea gesture type
[in]gesture_ida unique gesture identifier
[in]attrsparameters

◆ GeisGestureFuncs

The set of callback functions invoked for various gesture-related events.

An application must define callback functions to handle the various gesture events. These callbacks are provided in a table passed to geis_subscribe for each window on which gesture events may occur.

◆ GeisInputCallback

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

Prototype for input device callback functions.

◆ GeisInputFuncs

Callback functions used to handle changes in the available input devices.

Function Documentation

◆ geis_attr_name()

GeisString geis_attr_name ( GeisAttr  attr)

An opaque type that encapsulates a GEIS attribute.

GeisAttr objects may not be created or destroyed by the application, they may only have their data examined or extracted. Gets the name of an attribute.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_type()

GeisAttrType geis_attr_type ( GeisAttr  attr)

Gets the type of an attribute value.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_value_to_boolean()

GeisBoolean geis_attr_value_to_boolean ( GeisAttr  attr)

Gets the value of an attribute as a GeisBoolean.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_value_to_float()

GeisFloat geis_attr_value_to_float ( GeisAttr  attr)

Gets the value of an attribute as a GeisFloat.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_value_to_integer()

GeisInteger geis_attr_value_to_integer ( GeisAttr  attr)

Gets the value of an attribute as a GeisInteger.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_value_to_pointer()

GeisPointer geis_attr_value_to_pointer ( GeisAttr  attr)

Gets the value of an attribute as a GeisPointer.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_attr_value_to_string()

GeisString geis_attr_value_to_string ( GeisAttr  attr)

Gets the value of an attribute as a GeisString.

Parameters
[in]attrIdentifies the attribute.
Examples
geis2.c.

◆ geis_dispatch_events()

GeisStatus geis_dispatch_events ( Geis  geis)

Pumps the GEIS event loop.

Parameters
[in]geisThe GEIS API instance.

Processes input events until there are no more input events to process and generates zero or more gesture events, reporting them via the user-supplied callback or pushing them on the internal event queue for retrieval via the geis_next_event() call.

Return values
GEIS_STATUS_SUCCESSThe event loop was successfully pumped and no further events remain to be processed at this time.
GEIS_STATUS_CONTINUEThe event loop was successfully pumped but the system detected there are events still remaining to be processed.
GEIS_STATUS_UNKNOWN_ERRORSome error occurred
Examples
geis2.c.

◆ geis_event_attr()

GeisAttr geis_event_attr ( GeisEvent  event,
GeisSize  index 
)

Gets an indicated attribute from the event.

Parameters
[in]eventThe GeisEvent.
[in]indexIndicates the attribute to retrieve.

◆ geis_event_attr_by_name()

GeisAttr geis_event_attr_by_name ( GeisEvent  event,
GeisString  attr_name 
)

Gets a named attribute from the event.

Parameters
[in]eventThe GeisEvent.
[in]attr_nameThe name of the attribute to retrieve.
Examples
geis2.c.

◆ geis_event_attr_count()

GeisSize geis_event_attr_count ( GeisEvent  event)

Gets the number of attributes in the event.

Parameters
[in]eventThe GeisEvent.

◆ geis_event_delete()

void geis_event_delete ( GeisEvent  event)

Destroys a GeisEvent.

Parameters
[in]eventThe GeisEvent to destroy.
Examples
geis2.c.

◆ geis_event_type()

GeisEventType geis_event_type ( GeisEvent  event)

Gets the type of the event.

Parameters
[in]eventThe GeisEvent to destroy.
Examples
geis2.c.

◆ geis_get_configuration()

GeisStatus geis_get_configuration ( Geis  geis,
GeisString  configuration_item_name,
void *  configuration_item_value 
)

Gets a feature configuration value.

Parameters
[in]geisAn opaque GEIS API object.
[in]configuration_item_nameSelects the configuration value to return.
[out]configuration_item_valuePoints to a buffer to contain the output value. The actual type of this buffer depends on the configuration_value_name.
Return values
GEIS_STATUS_BAD_ARGUMENTan invalid argument value was passed
GEIS_STATUS_NOT_SUPPORTEDthe configuration value is not supported
GEIS_STATUS_SUCCESSnormal successful completion
Examples
geis2.c.

◆ geis_input_devices()

GeisStatus geis_input_devices ( GeisInstance  geis_instance,
GeisInputFuncs func,
void *  cookie 
)

Registers a callback to receive information on input devices.

Parameters
[in]geis_instancepoints to a geis gesture subscription instance
[in]funcpoints to a GeisInputFuncs table
[in]cookiean application specific value to be passed to the callback

The callback is called for each gesture-capable input device available for the display region associated with the geis subscription instance. Over time, as gesture-capable input devices appear and disappear or change their abilities or configuration, the callback may be called again.

Return values
GEIS_BAD_ARGUMENTan invalid argument value was passed
GEIS_STATUS_SUCCESSnormal successful completion

◆ geis_next_event()

GeisStatus geis_next_event ( Geis  geis,
GeisEvent event 
)

Retrieves the next queued GEIS event.

Parameters
[in]geisThe GEIS API instance.
[out]eventThe GeisEvent retrieved, if any.

Pulls the next available GeisEvent from the internal event queue, if any, and indicates whether there are more events left.

Return values
GEIS_STATUS_SUCCESSAn event was successfully pulled from the queue and the queue is now empty.
GEIS_STATUS_CONTINUEAn event was successfully pulled from the queue and one or more events remain in the queue.
GEIS_STATUS_EMPTYNo event was pulled from the queue because it is empty. The value of *event remains unchanged.
GEIS_STATUS_UNKNOWN_ERRORSome error occurred
Examples
geis2.c.

◆ geis_register_event_callback()

void geis_register_event_callback ( Geis  geis,
GeisEventCallback  event_callback,
void *  context 
)

Registers an event-handler callback.

Parameters
[in]geisthe GEIS API instance
[in]event_callbackthe callback to register
[in]contextthe caller context

This function registers the callback to be executed whenever a new GeisEvent is generated. The default function pushes the GeisEvent onto an internal queue to be picked up by a call to geis_next_event().

Calling geis_register_event_callback() with a callback of GEIS_DEFAULT_EVENT_CALLBACK replaces any registered function wit hthe default function.

The callback is executed in the same thread context as the one geis_dispatch_events() is called from.

◆ geis_set_configuration()

GeisStatus geis_set_configuration ( Geis  geis,
GeisString  configuration_item_name,
void *  configuration_item_value 
)

Sets a feature configuration value.

Parameters
[in]geisAn opaque GEIS API object.
[in]configuration_item_nameSelects the configuration value to return.
[in]configuration_item_valuePoints to a buffer to contain the output configuration value. The actual type of this buffer depends on the configuration_value_name.
Return values
GEIS_STATUS_BAD_ARGUMENTan invalid argument value was passed
GEIS_STATUS_NOT_SUPPORTEDthe configuration value is not supported
GEIS_STATUS_SUCCESSnormal successful completion

◆ geis_subscribe()

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

Registers a callback to receive gesture events.

Parameters
[in]geis_instancean opaque pointer to a geis gesture subscription instance
[in]input_lista null-terminated list of input device IDs
[in]gesture_lista null-terminated list of C-style strings naming gestures for subscription
[in]funcsa pointer to a GeisGestureFuncs structure
[in]cookiean application specific value to be passed to the callback
Return values
GEIS_BAD_ARGUMENTan invalid argument value was passed
GEIS_STATUS_SUCCESSnormal successful completion

◆ geis_unsubscribe()

GeisStatus geis_unsubscribe ( GeisInstance  geis_instance,
GeisGestureType *  gesture_list 
)

Unsubscribes to one or more gestures.

Parameters
[in]geis_instancean opaque pointer to a geis gesture subscription instance
[in]gesture_lista null-terminated list of gesture types