Loading...
Searching...
No Matches
Configuration
The Simplified GEIS Interface » Gesture Types » Gesture Primitives » Standard Gesture Types » Vendor Extension Gesture Types » Initialization and Cleanup » Configuration and Control | The Advanced GEIS Interface » The Geis API Object » Error Reporting

## Topics

| Input Devices

## Functions

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

## 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.
GeisStatus | geis_set_configuration (Geis geis, GeisString configuration_item_name, void *configuration_item_value)
| Sets a feature configuration value.
GeisStatus | geis_input_devices (GeisInstance geis_instance, GeisInputFuncs *func, void *cookie)
| Registers a callback to receive information on input devices.
GeisStatus | geis_subscribe (GeisInstance geis_instance, GeisInputDeviceId *input_list, const char **gesture_list, GeisGestureFuncs *funcs, void *cookie)
| Registers a callback to receive gesture events.
GeisStatus | geis_unsubscribe (GeisInstance geis_instance, GeisGestureType *gesture_list)
| Unsubscribes to one or more gestures.
GeisString | geis_attr_name (GeisAttr attr)
| An opaque type that encapsulates a GEIS attribute.
GeisAttrType | geis_attr_type (GeisAttr attr)
| Gets the type of an attribute value.
GeisBoolean | geis_attr_value_to_boolean (GeisAttr attr)
| Gets the value of an attribute as a GeisBoolean.
GeisFloat | geis_attr_value_to_float (GeisAttr attr)
| Gets the value of an attribute as a GeisFloat.
GeisInteger | geis_attr_value_to_integer (GeisAttr attr)
| Gets the value of an attribute as a GeisInteger.
GeisPointer | geis_attr_value_to_pointer (GeisAttr attr)
| Gets the value of an attribute as a GeisPointer.
GeisString | geis_attr_value_to_string (GeisAttr attr)
| Gets the value of an attribute as a GeisString.
void | geis_register_event_callback (Geis geis, GeisEventCallback event_callback, void *context)
| Registers an event-handler callback.
GeisStatus | geis_dispatch_events (Geis geis)
| Pumps the GEIS event loop.
GeisStatus | geis_next_event (Geis geis, GeisEvent *event)
| Retrieves the next queued GEIS event.
#define | GEIS_CONFIG_MAX_EVENTS
#define | GEIS_CONFIG_ATOMIC_GESTURES
| Indicates if atomic gestures are in use.
#define | GEIS_CONFIG_SEND_TENTATIVE_EVENTS
| See GEIS_INIT_SEND_TENTATIVE_EVENTS.
#define | GEIS_CONFIG_SEND_SYNCHRONOS_EVENTS
| See GEIS_INIT_SEND_SYNCHRONOS_EVENTS.
#define | GEIS_CONFIG_DRAG_THRESHOLD
| Movement threshold for recognizing a DRAG gesture (in meters).
#define | GEIS_CONFIG_DRAG_TIMEOUT
| Timeout for recognizing a DRAG gesture (in milliseconds).
#define | GEIS_CONFIG_PINCH_THRESHOLD
| Movement threshold for recognizing a PINCH gesture (in meters).
#define | GEIS_CONFIG_PINCH_TIMEOUT
| Timeout for recognizing a PINCH gesture (in milliseconds).
#define | GEIS_CONFIG_ROTATE_THRESHOLD
| Movement threshold for recognizing a ROTATE gesture (in meters).
#define | GEIS_CONFIG_ROTATE_TIMEOUT
| Timeout for recognizing a ROTATE gesture (in milliseconds).
#define | GEIS_CONFIG_TAP_THRESHOLD
| Movement threshold for recognizing a TAP gesture (in meters).
#define | GEIS_CONFIG_TAP_TIMEOUT
| Timeout for recognizing a TAP gesture (in milliseconds).
#define | GEIS_CONFIG_NUM_ACTIVE_SUBSCRIPTIONS
| The number of subscriptions currently active in the back end.
#define | GEIS_ALL_INPUT_DEVICES
#define | GEIS_ALL_GESTURES
| Selects ALL input devices.
#define | GEIS_NO_GESTURE_ID
#define | GEIS_DEFAULT_EVENT_CALLBACK
| A special constant indicating the use of the default event callback.

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.
typedef struct GeisInputFuncs | GeisInputFuncs
| Callback functions used to handle changes in the available input devices.
typedef unsigned int | GeisGestureType
typedef unsigned int | GeisGestureId
typedef struct GeisGestureAttr | GeisGestureAttr
| An individual gesture attribute.
typedef void(* | GeisGestureCallback) (void *cookie, GeisGestureType gesture_type, GeisGestureId gesture_id, GeisSize attr_count, GeisGestureAttr *attrs)
| A callback used for different gesture events.
typedef struct GeisGestureFuncs | GeisGestureFuncs
| The set of callback functions invoked for various gesture-related events.
typedef enum _GeisEventType | GeisEventType
typedef void(* | GeisEventCallback) (Geis geis, GeisEvent event, void *context)
| The application callback type for the event dispatcher.

## 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.

## 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] | geis | the GEIS API instance
  [in] | event | the opaque event pointer
  [in] | context | the application-supplied context value

## GeisGestureAttr

typedef struct GeisGestureAttr 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] | cookie | an application-specific value to be passed to the callback.
  [in] | gesture_type | a gesture type
  [in] | gesture_id | a unique gesture identifier
  [in] | attrs | parameters

## GeisGestureFuncs

typedef struct GeisGestureFuncs 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

typedef struct GeisInputFuncs 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] | attr | Identifies the attribute.

Examples
  geis2.c.

## geis_attr_type()

GeisAttrType geis_attr_type | ( | GeisAttr | attr | ) |

Gets the type of an attribute value.

Parameters

  [in] | attr | Identifies 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] | attr | Identifies 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] | attr | Identifies 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] | attr | Identifies 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] | attr | Identifies 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] | attr | Identifies the attribute.

Examples
  geis2.c.

## geis_dispatch_events()

GeisStatus geis_dispatch_events | ( | Geis | geis | ) |

Pumps the GEIS event loop.

Parameters

  [in] | geis | The 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_SUCCESS | The event loop was successfully pumped and no further events remain to be processed at this time.
  GEIS_STATUS_CONTINUE | The event loop was successfully pumped but the system detected there are events still remaining to be processed.
  GEIS_STATUS_UNKNOWN_ERROR | Some 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] | event | The GeisEvent.
  [in] | index | Indicates 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] | event | The GeisEvent.
  [in] | attr_name | The name of the attribute to retrieve.

## geis_event_attr_count()

GeisSize geis_event_attr_count | ( | GeisEvent | event | ) |

Gets the number of attributes in the event.

Parameters

  [in] | event | The GeisEvent.

## geis_event_delete()

void geis_event_delete | ( | GeisEvent | event | ) |

Destroys a GeisEvent.

Parameters

  [in] | event | The GeisEvent to destroy.

## geis_event_type()

GeisEventType geis_event_type | ( | GeisEvent | event | ) |

Gets the type of the event.

Parameters

  [in] | event | The GeisEvent to destroy.

## geis_get_configuration()

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

Gets a feature configuration value.

Parameters

  [in] | geis | An opaque GEIS API object.
  [in] | configuration_item_name | Selects the configuration value to return.
  [out] | configuration_item_value | Points 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_ARGUMENT | an invalid argument value was passed
  GEIS_STATUS_NOT_SUPPORTED | the configuration value is not supported
  GEIS_STATUS_SUCCESS | normal 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_instance | points to a geis gesture subscription instance
  [in] | func | points to a GeisInputFuncs table
  [in] | cookie | an 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_ARGUMENT | an invalid argument value was passed
  GEIS_STATUS_SUCCESS | normal successful completion

## geis_next_event()

GeisStatus geis_next_event | ( | Geis | geis,
|  | GeisEvent * | event )

Retrieves the next queued GEIS event.

Parameters

  [in] | geis | The GEIS API instance.
  [out] | event | The 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_SUCCESS | An event was successfully pulled from the queue and the queue is now empty.
  GEIS_STATUS_CONTINUE | An event was successfully pulled from the queue and one or more events remain in the queue.
  GEIS_STATUS_EMPTY | No event was pulled from the queue because it is empty. The value of *event remains unchanged.
  GEIS_STATUS_UNKNOWN_ERROR | Some 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] | geis | the GEIS API instance
  [in] | event_callback | the callback to register
  [in] | context | the 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] | geis | An opaque GEIS API object.
  [in] | configuration_item_name | Selects the configuration value to return.
  [in] | configuration_item_value | Points 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_ARGUMENT | an invalid argument value was passed
  GEIS_STATUS_NOT_SUPPORTED | the configuration value is not supported
  GEIS_STATUS_SUCCESS | normal 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_instance | an opaque pointer to a geis gesture subscription instance
  [in] | input_list | a null-terminated list of input device IDs
  [in] | gesture_list | a null-terminated list of C-style strings naming gestures for subscription
  [in] | funcs | a pointer to a GeisGestureFuncs structure
  [in] | cookie | an application specific value to be passed to the callback

Return values

  GEIS_BAD_ARGUMENT | an invalid argument value was passed
  GEIS_STATUS_SUCCESS | normal successful completion

## geis_unsubscribe()

GeisStatus geis_unsubscribe | ( | GeisInstance | geis_instance,
|  | GeisGestureType * | gesture_list )

Unsubscribes to one or more gestures.

Parameters

  [in] | geis_instance | an opaque pointer to a geis gesture subscription instance
  [in] | gesture_list | a null-terminated list of gesture types