geis.h   geis.h 
/** /**
* geis.h * @file geis/geis.h
* This is the public interface for the GEIS gesture API.
* *
* Copyright 2010 Canonical Ltd. * Copyright 2010, 2011 Canonical Ltd.
* *
* This library is free software; you can redistribute it and/or modify it under * This library is free software; you can redistribute it and/or modify it under
* the terms of the GNU Lesser General Public License as published by the F ree * the terms of the GNU Lesser General Public License as published by the F ree
* Software Foundation; either version 3 of the License, or (at your option ) any * Software Foundation; either version 3 of the License, or (at your option ) any
* later version. * later version.
* *
* This library is distributed in the hope that it will be useful, but WITH OUT * This library is distributed in the hope that it will be useful, but WITH OUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FI TNESS * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FI TNESS
* FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License f or * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License f or
* more details. * more details.
skipping to change at line 28 skipping to change at line 29
* Franklin St, Fifth Floor, Boston, MA 02110-1301 US * Franklin St, Fifth Floor, Boston, MA 02110-1301 US
*/ */
#ifndef GEIS_GEIS_H_ #ifndef GEIS_GEIS_H_
#define GEIS_GEIS_H_ #define GEIS_GEIS_H_
#ifdef __cplusplus #ifdef __cplusplus
extern "C" { extern "C" {
#endif #endif
#define GEIS_VERSION_1_0 1 #define GEIS_VERSION_1_0 1
#define GEIS_VERSION_2_0 20101122
#include <geis/geisimpl.h> #include <geis/geisimpl.h>
/* Standard fundamental gestures */ /* Standard fundamental gestures */
#define GEIS_GESTURE_DRAG "Drag" #define GEIS_GESTURE_DRAG "Drag"
#define GEIS_GESTURE_PINCH "Pinch" #define GEIS_GESTURE_PINCH "Pinch"
#define GEIS_GESTURE_ROTATE "Rotate" #define GEIS_GESTURE_ROTATE "Rotate"
#define GEIS_GESTURE_TAP "Tap" #define GEIS_GESTURE_TAP "Tap"
/**
* @defgroup geis_v1_gesture_types Standard Gesture Types (GEIS v1)
* The names of standard gesture types. These names can be passed to
* geis_subscribe() in a NULL-terminated list to specify only a subset of
* available gestures.
* @{
*/
/* Gesture names for the Simplified Interface */ /* Gesture names for the Simplified Interface */
#define GEIS_GESTURE_TYPE_DRAG1 "Drag,touch=1" #define GEIS_GESTURE_TYPE_DRAG1 "Drag,touch=1"
#define GEIS_GESTURE_TYPE_DRAG2 "Drag,touch=2" #define GEIS_GESTURE_TYPE_DRAG2 "Drag,touch=2"
#define GEIS_GESTURE_TYPE_DRAG3 "Drag,touch=3" #define GEIS_GESTURE_TYPE_DRAG3 "Drag,touch=3"
#define GEIS_GESTURE_TYPE_DRAG4 "Drag,touch=4" #define GEIS_GESTURE_TYPE_DRAG4 "Drag,touch=4"
#define GEIS_GESTURE_TYPE_DRAG5 "Drag,touch=5" #define GEIS_GESTURE_TYPE_DRAG5 "Drag,touch=5"
#define GEIS_GESTURE_TYPE_PINCH1 "Pinch,touch=1" #define GEIS_GESTURE_TYPE_PINCH1 "Pinch,touch=1"
#define GEIS_GESTURE_TYPE_PINCH2 "Pinch,touch=2" #define GEIS_GESTURE_TYPE_PINCH2 "Pinch,touch=2"
#define GEIS_GESTURE_TYPE_PINCH3 "Pinch,touch=3" #define GEIS_GESTURE_TYPE_PINCH3 "Pinch,touch=3"
#define GEIS_GESTURE_TYPE_PINCH4 "Pinch,touch=4" #define GEIS_GESTURE_TYPE_PINCH4 "Pinch,touch=4"
skipping to change at line 59 skipping to change at line 69
#define GEIS_GESTURE_TYPE_ROTATE2 "Rotate,touch=2" #define GEIS_GESTURE_TYPE_ROTATE2 "Rotate,touch=2"
#define GEIS_GESTURE_TYPE_ROTATE3 "Rotate,touch=3" #define GEIS_GESTURE_TYPE_ROTATE3 "Rotate,touch=3"
#define GEIS_GESTURE_TYPE_ROTATE4 "Rotate,touch=4" #define GEIS_GESTURE_TYPE_ROTATE4 "Rotate,touch=4"
#define GEIS_GESTURE_TYPE_ROTATE5 "Rotate,touch=5" #define GEIS_GESTURE_TYPE_ROTATE5 "Rotate,touch=5"
#define GEIS_GESTURE_TYPE_TAP1 "Tap,touch=1" #define GEIS_GESTURE_TYPE_TAP1 "Tap,touch=1"
#define GEIS_GESTURE_TYPE_TAP2 "Tap,touch=2" #define GEIS_GESTURE_TYPE_TAP2 "Tap,touch=2"
#define GEIS_GESTURE_TYPE_TAP3 "Tap,touch=3" #define GEIS_GESTURE_TYPE_TAP3 "Tap,touch=3"
#define GEIS_GESTURE_TYPE_TAP4 "Tap,touch=4" #define GEIS_GESTURE_TYPE_TAP4 "Tap,touch=4"
#define GEIS_GESTURE_TYPE_TAP5 "Tap,touch=5" #define GEIS_GESTURE_TYPE_TAP5 "Tap,touch=5"
/* @} */
/**
* @defgroup geis_v1_vendor_extensions Vendor Extensions (GEIS v1)
* Vendor-specific extensions to the GEIS v1 API.
* @{
*/
/**
* A special gesture type than enabled system-wide gesture priority.
*/
#define GEIS_GESTURE_TYPE_SYSTEM "Sysflags"
/* @} */
/* Standard fundamental gesture attributes */ /* Standard fundamental gesture attributes */
#define GEIS_GESTURE_ATTRIBUTE_ANGLE "angle" #define GEIS_GESTURE_ATTRIBUTE_ANGLE "angle"
#define GEIS_GESTURE_ATTRIBUTE_ANGLE_DELTA "angle delta" #define GEIS_GESTURE_ATTRIBUTE_ANGLE_DELTA "angle delta"
#define GEIS_GESTURE_ATTRIBUTE_ANGULAR_VELOCITY "angular velocity" #define GEIS_GESTURE_ATTRIBUTE_ANGULAR_VELOCITY "angular velocity"
#define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X1 "boundingbox x1" #define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X1 "boundingbox x1"
#define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y1 "boundingbox y1" #define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y1 "boundingbox y1"
#define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X2 "boundingbox x2" #define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_X2 "boundingbox x2"
#define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y2 "boundingbox y2" #define GEIS_GESTURE_ATTRIBUTE_BOUNDINGBOX_Y2 "boundingbox y2"
#define GEIS_GESTURE_ATTRIBUTE_CHILD_WINDOW_ID "child window id" #define GEIS_GESTURE_ATTRIBUTE_CHILD_WINDOW_ID "child window id"
#define GEIS_GESTURE_ATTRIBUTE_DELTA_X "delta x" #define GEIS_GESTURE_ATTRIBUTE_DELTA_X "delta x"
skipping to change at line 102 skipping to change at line 127
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_ID "touch 2 id" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_ID "touch 2 id"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_X "touch 2 x" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_X "touch 2 x"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_Y "touch 2 y" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_2_Y "touch 2 y"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_ID "touch 3 id" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_ID "touch 3 id"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_X "touch 3 x" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_X "touch 3 x"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_Y "touch 3 y" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_3_Y "touch 3 y"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_ID "touch 4 id" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_ID "touch 4 id"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_X "touch 4 x" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_X "touch 4 x"
#define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_Y "touch 4 y" #define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_Y "touch 4 y"
#define GEIS_TOUCH_ATTRIBUTE_ID "touch id"
#define GEIS_TOUCH_ATTRIBUTE_X "touch x"
#define GEIS_TOUCH_ATTRIBUTE_Y "touch y"
#define GEIS_DEVICE_ATTRIBUTE_NAME "device name"
#define GEIS_REGION_ATTRIBUTE_WINDOWID "windowid"
#define GEIS_FALSE 0
#define GEIS_TRUE 1
/** /**
* @defgroup geis_status Status and Errors * @defgroup geis_status Status and Errors
* *
* Most GEIS API calls return a status code indicating success or, in the e vent * Most GEIS API calls return a status code indicating success or, in the e vent
* of a lack of success, the reson for failure. * of a lack of success, the reson for failure.
* *
* @{ * @{
*/ */
/** /**
* Errors returned from calls. * Errors returned from calls.
*/ */
typedef enum GeisStatus typedef enum GeisStatus
{ {
GEIS_STATUS_SUCCESS = 0, /**< normal successful completion */ GEIS_STATUS_SUCCESS = 0, /**< normal successful completion */
GEIS_STATUS_CONTINUE = 20, /**< normal successful completion
with data still remaining */
GEIS_STATUS_EMPTY = 21, /**< normal successful completion
with no data retrieved */
GEIS_STATUS_NOT_SUPPORTED = 10, /**< a requested feature is not support ed */ GEIS_STATUS_NOT_SUPPORTED = 10, /**< a requested feature is not support ed */
GEIS_BAD_ARGUMENT = 1000, /**< a bad argument value was passed */ GEIS_BAD_ARGUMENT = 1000, /**< a bad argument value was passed */
GEIS_UNKNOWN_ERROR = 9999 /**< any other error condition */ GEIS_UNKNOWN_ERROR = 9999, /**< any other error condition */
GEIS_STATUS_BAD_ARGUMENT = -100, /**< a bad argument value was passed */
GEIS_STATUS_UNKNOWN_ERROR = -999 /**< any other error condition */
} GeisStatus; } GeisStatus;
/* @} */ /* @} */
/** /**
* @defgroup geis_meta Initialization and Cleanup * @defgroup geis_meta Initialization and Cleanup
* *
* Each instance of a gesture subscription must be created using the geis_i nit() * Each instance of a gesture subscription must be created using the geis_i nit()
* call and destroyed using the geis_finish() call. * call and destroyed using the geis_finish() call.
* *
skipping to change at line 185 skipping to change at line 227
* instance * instance
* *
* @retval GEIS_BAD_ARGUMENT an invalid GeisInstance was passed * @retval GEIS_BAD_ARGUMENT an invalid GeisInstance was passed
* @retval GEIS_STATUS_SUCCESS normal successful completion * @retval GEIS_STATUS_SUCCESS normal successful completion
*/ */
GEIS_API GeisStatus geis_finish(GeisInstance geis_instance); GEIS_API GeisStatus geis_finish(GeisInstance geis_instance);
/* @} */ /* @} */
/** /**
* @defgroup geis_config Configuration and Control * @defgroup geis_2_geis The Geis API Object (GEIS v2.0)
*
* @{
*/
/**
* @defgroup geis_2_geis_init_args Specified Initialization Arguments
*
* These initialization arguments are defined by the GEIS specification.
*
* @{
*/
/**
* Enables GEIS to provide a networked service.
*
* This initialization argument takes no parameters.
*/
#define GEIS_INIT_SERVICE_PROVIDER "org.libgeis.init.server"
/**
* Tells GEIS to send input device events.
*
* This initialization argument takes no parameters.
*/
#define GEIS_INIT_TRACK_DEVICES "org.libgeis.init.track-devices"
/**
* Tells GEIS to send gesture class events.
*
* This initialization argument takes no parameters.
*/
#define GEIS_INIT_TRACK_GESTURE_CLASSES "org.libgeis.init.track-gesture-cl
asses"
/* @} */
/**
* @defgroup geis_2_geis_init_vendor Vendor-defined Initialization Argument
s
*
* These initialization arguments are not a part of te GEIS specification a
nd
* may change.
*
* @{
*/
#define GEIS_INIT_UTOUCH_MOCK_ENGINE "com.canonical.utouch.mock.engine"
#define GEIS_INIT_UTOUCH_XCB "com.canonical.utouch.xcb"
/* @} */
typedef struct _Geis *Geis;
/**
* Initializes an instance of the GEIS v2.0 API.
*
* @param[in] name A name for the API instance (used for diagnostics).
* @param[in] ... A set of zero or more initialization arguments.
*/
GEIS_API Geis geis_new(GeisString init_arg_name, ...);
/**
* Cleans up an instance of the GEIS v2.0 API.
*
* @param[in] geis An instance of the GEIS v2.0 API.
*
* Tears down the instance of the API and releases any resources associated
with
* that instance.
*/
GEIS_API GeisStatus geis_delete(Geis geis);
/* @} */
/**
* @defgroup geis_error Error Reporting
* @{
*/
/**
* Gets the number of status codes in the error stack.
*
* @param[in] geis A GEIS API instance or NULL for the global stack
*
* This function is used primarily to determine the failure details of a GE
IS
* function that does not explicitly return a GeisStatus value. This is
* required for _new() fucntions that return NULL to indicate failure. If
the
* call to geis_new() itself fails and returns a NULL, the global error sta
ck
* must be used, otherwise the API instance error stack must be used.
*
* The error stack is reset on each GEIS API call, so failure reasons shoul
d be
* determined immmediately after a GEIS API call.
*/
GEIS_API GeisSize geis_error_count(Geis geis);
/**
* Gets the indicated status code from the error stack.
*
* @param[in] geis A GEIS API instance or NULL for the global stack
* @param[in] index Indicates the status value to retrieve. Valid status v
alues
* are between 0 and less than the value returned from
* geis_error_count() otherwise GEIS_STATUS_BAD_ARGUMENT w
ill
* be returned.
*/
GEIS_API GeisStatus geis_error_code(Geis geis, GeisSize index);
/**
* Gets the localized error message, if any, associated with the indicated
* error.
*
* @param[in] geis A GEIS API instance or NULL for the global stack
* @param[in] index Indicates the status value to retrieve. Valid status v
alues
* are between 0 and less than the value returned from
* geis_error_count() otherwise GEIS_STATUS_BAD_ARGUMENT w
ill
* be returned.
*/
GEIS_API GeisString geis_error_message(Geis geis, GeisSize index);
/* @} */
/**
* @defgroup geis1_config Configuration and Control (GEIS v1.0)
* @{ * @{
*/ */
#define GEIS_CONFIG_UNIX_FD 10001 #define GEIS_CONFIG_UNIX_FD 10001
/** /**
* Indicates if a particular feaure is supported. * Indicates if a particular feaure is supported.
* *
* @param[in] geis_instance an opaque pointer to a geis gesture subscri ption * @param[in] geis_instance an opaque pointer to a geis gesture subscri ption
* instance * instance
skipping to change at line 245 skipping to change at line 406
* This function is used to integrate geis even dispatch into the main even t * This function is used to integrate geis even dispatch into the main even t
* loop of an application or toolkit. * loop of an application or toolkit.
* *
* @retval GEIS_BAD_ARGUMENT an invalid GeisInstance was passed * @retval GEIS_BAD_ARGUMENT an invalid GeisInstance was passed
* @retval GEIS_STATUS_SUCCESS normal successful completion * @retval GEIS_STATUS_SUCCESS normal successful completion
*/ */
GEIS_API GeisStatus geis_event_dispatch(GeisInstance geis_instance); GEIS_API GeisStatus geis_event_dispatch(GeisInstance geis_instance);
/* @} */ /* @} */
/**
* @defgroup geis2_config Configuration (GEIS v2.0)
* @{
*/
/**
* @defgroup geis2_config_spec Required Configuration Items
*
* These configuration items are defined by the GEIS specification.
*
* @{
*/
#define GEIS_CONFIGURATION_FD "org.libgeis.configuration.fd"
/* @} */
/**
* @defgroup geis2_config_vendor Vendor-defined Configuration Items
*
* These configuration items are not a part of the GEIS specification and m
ay
* change.
*
* @{
*/
#define GEIS_CONFIG_UTOUCH_MAX_EVENTS "com.canonical.utouch.max_events"
/* @} */
/**
* Gets a feature configuration value.
*
* @param[in] geis An opaque GEIS API object.
* @param[in] configuration_item_name Selects the configuration value to
return.
* @param[out] configuration_item_value Points to a buffer to contain the o
utput
* value. The actual type of this buf
fer
* depends on the
* @p configuration_value_name.
*
* @retval GEIS_STATUS_BAD_ARGUMENT an invalid argument value was passed
* @retval GEIS_STATUS_NOT_SUPPORTED the configuration value is not suppor
ted
* @retval GEIS_STATUS_SUCCESS normal successful completion
*/
GEIS_API GeisStatus geis_get_configuration(Geis geis,
GeisString configuration_item_n
ame,
void *configuration_item_v
alue);
/**
* Sets a feature configuration value.
*
* @param[in] geis An opaque GEIS API object.
* @param[in] configuration_value Selects the configuration value to retu
rn.
* @param[in] configuration_item_name Selects the configuration value to
return.
* @param[in] configuration_item_value Points to a buffer to contain the ou
tput
* configuration value. The actual typ
e of
* this buffer depends on the
* @p configuration_value_name.
*
* @retval GEIS_STATUS_BAD_ARGUMENT an invalid argument value was passed
* @retval GEIS_STATUS_NOT_SUPPORTED the configuration value is not suppor
ted
* @retval GEIS_STATUS_SUCCESS normal successful completion
*/
GEIS_API GeisStatus geis_set_configuration(Geis geis,
GeisString configuration_item_n
ame,
void *configuration_item_v
alue);
/* @} */
/**
* @defgroup geis2_attrs Attributes
*
* Attributes are named values associated with various GEIS entities, inclu
ding
* input devices, gesture types, and gesture events.
*
* @{
*/
typedef enum GeisAttrType typedef enum GeisAttrType
{ {
GEIS_ATTR_TYPE_UNKNOWN, GEIS_ATTR_TYPE_UNKNOWN,
GEIS_ATTR_TYPE_BOOLEAN, GEIS_ATTR_TYPE_BOOLEAN,
GEIS_ATTR_TYPE_FLOAT, GEIS_ATTR_TYPE_FLOAT,
GEIS_ATTR_TYPE_INTEGER, GEIS_ATTR_TYPE_INTEGER,
GEIS_ATTR_TYPE_POINTER,
GEIS_ATTR_TYPE_STRING GEIS_ATTR_TYPE_STRING
} GeisAttrType; } GeisAttrType;
/** /**
* An opaque type that encapsulates a GEIS attribute.
*
* GeisAttr objects may not be created or destroyed by the application, the
y may
* only have their data examined or extracted.
*/
typedef struct _GeisAttr *GeisAttr;
/**
* Gets the name of an attribute.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisString geis_attr_name(GeisAttr attr);
/**
* Gets the type of an attribute value.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisAttrType geis_attr_type(GeisAttr attr);
/**
* Gets the value of an attribute as a GeisBoolean.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisBoolean geis_attr_value_to_boolean(GeisAttr attr);
/**
* Gets the value of an attribute as a GeisFloat.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisFloat geis_attr_value_to_float(GeisAttr attr);
/**
* Gets the value of an attribute as a GeisInteger.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisInteger geis_attr_value_to_integer(GeisAttr attr);
/**
* Gets the value of an attribute as a GeisPointer.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisPointer geis_attr_value_to_pointer(GeisAttr attr);
/**
* Gets the value of an attribute as a GeisString.
*
* @param[in] attr Identifies the attribute.
*/
GEIS_API GeisString geis_attr_value_to_string(GeisAttr attr);
/* @} */
/**
* @defgroup geis_input Input Devices * @defgroup geis_input Input Devices
* @{ * @{
*/ */
typedef unsigned int GeisInputDeviceId; typedef unsigned int GeisInputDeviceId;
#define GEIS_ALL_INPUT_DEVICES ((GeisInputDeviceId)0) #define GEIS_ALL_INPUT_DEVICES ((GeisInputDeviceId)0)
/** /**
* Prototype for input device callback functions. * Prototype for input device callback functions.
skipping to change at line 305 skipping to change at line 603
* @retval GEIS_BAD_ARGUMENT an invalid argument value was passed * @retval GEIS_BAD_ARGUMENT an invalid argument value was passed
* @retval GEIS_STATUS_SUCCESS normal successful completion * @retval GEIS_STATUS_SUCCESS normal successful completion
*/ */
GEIS_API GeisStatus geis_input_devices(GeisInstance geis_instance, GEIS_API GeisStatus geis_input_devices(GeisInstance geis_instance,
GeisInputFuncs *func, GeisInputFuncs *func,
void *cookie); void *cookie);
/* @} */ /* @} */
/** /**
* @defgroup geis_subscription Gesture Subscription * @defgroup geis1_subscription Gesture Subscription (GEIS v1.0)
* @{ * @{
*/ */
typedef unsigned int GeisGestureType; typedef unsigned int GeisGestureType;
typedef unsigned int GeisGestureId; typedef unsigned int GeisGestureId;
#define GEIS_ALL_GESTURES ((GeisGestureType)0) #define GEIS_ALL_GESTURES ((GeisGestureType)0)
#define GEIS_NO_GESTURE_ID ((GeisGestureId)0) #define GEIS_NO_GESTURE_ID ((GeisGestureId)0)
/** /**
* Gesture Attributes * Gesture Attributes
skipping to change at line 390 skipping to change at line 688
* *
* @param[in] geis_instance an opaque pointer to a geis gesture subscri ption * @param[in] geis_instance an opaque pointer to a geis gesture subscri ption
* instance * instance
* @param[in] gesture_list a null-terminated list of gesture types * @param[in] gesture_list a null-terminated list of gesture types
*/ */
GEIS_API GeisStatus geis_unsubscribe(GeisInstance geis_instance, GEIS_API GeisStatus geis_unsubscribe(GeisInstance geis_instance,
GeisGestureType *gesture_list); GeisGestureType *gesture_list);
/* @} */ /* @} */
/**
* @defgroup geis2_event_control Event Control (GEIS v2.0)
*
* These functions are used to dispatch events generated from the various o
ther
* GEIS components.
*
* Applications must invoke geis_dispatch_events() from time to time to gen
erate
* input device, gesture type, and gesture events. The GEIS events are the
n
* retrieved either from the internal event queue using the geis_next_event
()
* call or through an application-supplied callback set through the
* geis_register_event_callback() call.
*
* @{
*/
typedef enum _GeisEventType
{
GEIS_EVENT_DEVICE_AVAILABLE = 1000,
GEIS_EVENT_DEVICE_UNAVAILABLE = 1010,
GEIS_EVENT_CLASS_AVAILABLE = 2000,
GEIS_EVENT_CLASS_CHANGED = 2005,
GEIS_EVENT_CLASS_UNAVAILABLE = 2010,
GEIS_EVENT_GESTURE_BEGIN = 3000,
GEIS_EVENT_GESTURE_UPDATE = 3010,
GEIS_EVENT_GESTURE_END = 3020,
GEIS_EVENT_INIT_COMPLETE = 4000,
GEIS_EVENT_USER_DEFINED = 6000,
GEIS_EVENT_ERROR = 7000
} GeisEventType;
/**
* Opaque pointer to a generic GEIS event.
*
* Applications must determine the type of the actual event and convert the
* opaque pointer to a concrete event pointer, if required.
*
* Events are created by the GEIS API but must be destroyed by the applicat
ion.
*/
typedef struct _GeisEvent *GeisEvent;
/**
* Destroys a GeisEvent.
*
* @param[in] geis The GeisEvent to destroy.
*/
GEIS_API void geis_event_delete(GeisEvent event);
/**
* Gets the type of the event.
*
* @param[in] geis The GeisEvent to destroy.
*/
GEIS_API GeisEventType geis_event_type(GeisEvent event);
/**
* Gets the number of attributes in the event.
*
* @param[in] geis The GeisEvent.
*/
GEIS_API GeisSize geis_event_attr_count(GeisEvent event);
/**
* Gets an indicated attribute from the event.
*
* @param[in] geis The GeisEvent.
* @param[in] index Indicates the attribute to retrieve.
*/
GEIS_API GeisAttr geis_event_attr(GeisEvent event, GeisSize index);
/**
* Gets a named attribute from the event.
*
* @param[in] geis The GeisEvent.
* @param[in] attr_name The name of the attribute to retrieve.
*/
GEIS_API GeisAttr geis_event_attr_by_name(GeisEvent event, GeisString attr_
name);
/**
* The application callback type for the event dispatcher.
*
* @param[in] geis the GEIS API instance
* @param[in] event the opaque event pointer
* @param[in] context the application-supplied context value
*/
typedef void (*GeisEventCallback)(Geis geis, GeisEvent event, void *context
);
/**
* A special constant indicating the use of the default event callback.
*/
#define GEIS_DEFAULT_EVENT_CALLBACK ((GeisEventCallback)0)
/**
* Registers an event-handler callback.
*
* @param[in] geis the GEIS API instance
* @param[in] event_callback the callback to register
* @param[in] context the caller context
*
* This function registers the callback to be executed whenever a new GeisE
vent
* is generated. The default function pushes the GeisEvent onto an interna
l
* 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 de
fault
* function.
*
* The callback is executed in the same thread context as the one
* geis_dispatch_events() is called from.
*/
GEIS_API void geis_register_event_callback(Geis geis,
GeisEventCallback event_callbac
k,
void *context);
/**
* Pumps the GEIS event loop.
*
* @param[in] geis The GEIS API instance.
* @param[out] event An opeaque event object.
*
* Processes input events until there are no more input events to process a
nd
* generates zero or more gesture events, reporting them via the user-suppl
ied
* callback or pushing them on the internal event queue for retrieval via t
he
* geis_next_event() call.
*
* @retval GEIS_STATUS_SUCCESS The event loop was successfully pumped
and
* no further events remain to be process
ed at
* this time.
*
* @retval GEIS_STATUS_CONTINUE The event loop was successfully pumped
but
* the system detected there are events
* still remaining to be processed.
*
* @retval GEIS_STATUS_UNKNOWN_ERROR Some error occurred
*/
GEIS_API GeisStatus geis_dispatch_events(Geis geis);
/**
* Retrieves the next queued GEIS event.
*
* @param[in] geis The GEIS API instance.
* @param[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.
*
* @retval GEIS_STATUS_SUCCESS An event was successfully pulled from
the
* queue and the queue is now empty.
*
* @retval GEIS_STATUS_CONTINUE An event was successfully pulled from
the
* queue and one or more events remain in
the
* queue.
*
* @retval GEIS_STATUS_EMPTY No event was pulled from the queue bec
ause
* it is empty. The value of *event rema
ins
* unchanged.
*
* @retval GEIS_STATUS_UNKNOWN_ERROR Some error occurred
*/
GEIS_API GeisStatus geis_next_event(Geis geis, GeisEvent *event);
/* @} */
/**
* @defgroup geis2_device Gesture Input Devices (GEIS v2.0)
* @{
*/
/**
* An opaque pointer type representing a gesture-capable input device.
*
* GeisDevice objects are created by the GEIS API and are reference counted
.
*/
typedef struct _GeisDevice *GeisDevice;
GEIS_API void geis_register_device_callback(Geis geis,
GeisEventCallback event_callba
ck,
void *context);
/**
* Adds a reference count to a device.
*
* @param[in] device The device.
*
* An application that wishes to guarantee the device object remains valid
* should add a reference using this call, and unref when the object is no
* longer needed.
*/
GEIS_API void geis_device_ref(GeisDevice device);
/**
* Removes a reference count from a device.
*
* @param[in] device The device.
*
* This function decrements the number of references to the device and, if
the
* number of references hits zero, deletes the device.
*/
GEIS_API void geis_device_unref(GeisDevice device);
/**
* Gets the name of the input device.
*
* @param[in] device The device.
*/
GEIS_API GeisString geis_device_name(GeisDevice device);
/**
* Gets the system identifier of the iput device.
*
* @param[in] device The device.
*
* The system-defined device identifier is system- and possibly
* device-dependent.
*/
GEIS_API GeisInteger geis_device_id(GeisDevice device);
/**
* Gets the number of attributes of the device.
*
* @param[in] device The device.
*/
GEIS_API GeisSize geis_device_attr_count(GeisDevice device);
/**
* Gets the indicated attribute of the device.
*
* @param[in] device The device.
*/
GEIS_API GeisAttr geis_device_attr(GeisDevice device, GeisSize index);
/* @} */
/**
* @defgroup geis2_class Gesture Classes (GEIS v2.0)
* @{
*/
/**
* An opaque pointer type representing a gesture-capable input device.
*
* GeisDevice objects are created by the GEIS API and are reference counted
. An
* application needs to increment and decrement the reference count of a ge
sture
* class object to control its persistence.
*/
typedef struct _GeisGestureClass *GeisGestureClass;
#define GEIS_CLASS_ATTRIBUTE_NAME "class name"
#define GEIS_CLASS_ATTRIBUTE_ID "class id"
#define GEIS_EVENT_ATTRIBUTE_CLASS "gesture class"
/**
* Registers a callback to receive gesture class change notifications.
*
* @param[in] geis The API instance.
* @param[in] event_callback The callback function.
* @param[in] context Contextual data to be passed through to the
* callback.
*
* This function is used to register a function to be executed when a chang
e to
* the available gesture class definitions has occurred. If no function is
* registered, the default action is to deliver gesture class events throug
h the
* main event mechanism.
*
* Passing a value of GEIS_DEFAULT_EVENT_CALLBACK as the @p event-callback
will
* reset the callback function to the default action.
*
* The @p event_callback function will be executed in the same thread conte
xt as
* geis_dispatch_events().
*/
GEIS_API void geis_register_class_callback(Geis geis,
GeisEventCallback event_callbac
k,
void *context);
/**
* Increments the reference count of a gesture class object.
*
* @param[in] gesture_class The gesture class object.
*/
GEIS_API void geis_gesture_class_ref(GeisGestureClass gesture_class);
/**
* Decrements the reference count of a gesture class object.
*
* @param[in] gesture_class The gesture class object.
*
* The reference count of teh object is decremented and, if it reaches zero
, the
* object is destroyed.
*/
GEIS_API void geis_gesture_class_unref(GeisGestureClass gesture_class);
/**
* Gets the name of the gesture class.
*
* @param[in] gesture_class The gesture class object.
*/
GEIS_API GeisString geis_gesture_class_name(GeisGestureClass gesture_class)
;
/**
* Gets the numeric identifier of the gesture class.
*
* @param[in] gesture_class The gesture class object.
*/
GEIS_API GeisInteger geis_gesture_class_id(GeisGestureClass gesture_class);
/**
* Gets the number of attributes of the gesture class.
*
* @param[in] gesture_class The gesture class object.
*/
GEIS_API GeisSize geis_gesture_class_attr_count(GeisGestureClass gesture_cl
ass);
/**
* Gets the indicated attribute of teh gesture class.
*
* @param[in] gesture_class The gesture class object.
* @param[in] index The index of the attribute to retrieve.
*/
GEIS_API GeisAttr geis_gesture_class_attr(GeisGestureClass gesture_class,
int index);
/* @} */
/**
* @defgroup geis2_region Gesture Regions (GEIS v2.0)
* @{
*/
typedef struct _GeisRegion *GeisRegion;
/**
* @defgroup geis2_region_init_args Gesture Region Initialization Arguments
*
* Gesture regions are created to describe a particular display/feedback re
gion.
* The type of the region can not be changed after creation (just create a
new
* region for that). The types of regions are platform specific and each t
ype
* may require addition arguments.
*
* The following region initialization argument names are required by the
* GEIS v2.0 specification.
*
* @{
*/
#define GEIS_REGION_X11_ROOT "org.libgeis.region.x11.root"
#define GEIS_REGION_X11_WINDOWID "org.libgeis.region.x11.windowid"
/* @} */
/**
* Creates a new GEIS v2.0 region.
*
* @param[in] geis The GEIS API instance.
* @param[in] name A name. Used for diagnostics.
* @param[in] init_arg_name The name of the first initialization argument.
*
* The initialization argument list must be terminated by a NULL.
*
* @returns a newly created region, or NULL on failure.
*/
GEIS_API GeisRegion geis_region_new(Geis geis,
GeisString name,
GeisString init_arg_name, ...);
/**
* Destroys a GEIS v2.0 region.
*
* @param[in] region The region.
*/
GEIS_API GeisStatus geis_region_delete(GeisRegion region);
/**
* Gets the name of a GEIS v2.0 region.
*
* @param[in] region The region.
*
* Returns the @p name value used when creating the region.
*/
GEIS_API GeisString geis_region_name(GeisRegion region);
/* @} */
/**
* @defgroup geis2_filter Gesture Filter (GEIS v2.0)
* @{
*/
typedef struct _GeisFilter *GeisFilter;
typedef enum _GeisFilterFacility
{
GEIS_FILTER_DEVICE = 1000,
GEIS_FILTER_CLASS = 2000,
GEIS_FILTER_REGION = 3000
} GeisFilterFacility;
typedef enum _GeisFilterOperation
{
GEIS_FILTER_OP_EQ,
GEIS_FILTER_OP_NE,
GEIS_FILTER_OP_GT,
GEIS_FILTER_OP_GE,
GEIS_FILTER_OP_LT,
GEIS_FILTER_OP_LE
} GeisFilterOperation;
/**
* Creates a new, empty filter.
*
* @param[in] geis The GEIS API instance.
* @param[in] name A name.
*
* @returns a GeisFilter object or NULL on failure.
*/
GEIS_API GeisFilter geis_filter_new(Geis geis, GeisString name);
/**
* Creates a new filter by copying an existing filter.
*
* @param[in] original An existing geisFilter instance.
* @param[in] name A name.
*
* @returns a GeisFilter object or NULL on failure.
*/
GEIS_API GeisFilter geis_filter_clone(GeisFilter original, GeisString name)
;
/**
* Destroys a GEIS v2.0 filter object.
*
* @param[in] filter The filter.
*/
GEIS_API GeisStatus geis_filter_delete(GeisFilter filter);
/**
* Gets the name given to the filter when it was created.
*
* @param[in] filter The filter.
*/
GEIS_API GeisString geis_filter_name(GeisFilter filter);
/**
* Adds a term to a filter.
*
* @param[in] filter The filter.
* @param[in] facility The term facility.
* @param[in] ... A list of zero or more term descriptions.
*
* A term description is generally a (attr-name, filter-op, value) triple i
n
* which the meaning of the filter-op and value depend on the type of the a
ttr.
*
* The term description list must be terminated by a NULL.
*/
GEIS_API GeisStatus geis_filter_add_term(GeisFilter filter,
GeisFilterFacility facility,
...);
/* @} */
/**
* @defgroup geis2_subscription Gesture Subscription (GEIS v2.0)
* @{
*/
typedef struct _GeisSubscription *GeisSubscription;
/**
* Flags to refine the behaviour of the gesture subscription.
*/
typedef enum _GeisSubscriptionFlags
{
GEIS_SUBSCRIPTION_NONE = 0x0000,
GEIS_SUBSCRIPTION_GRAB = 0x0001,
GEIS_SUBSCRIPTION_CONT = 0x0002
} GeisSubscriptionFlags;
/**
* Creates a new subscription.
*
* @param[in] geis The GEIS API instance.
* @param[in] name A name.
* @param[in] flags Some flags.
*
* @returns a GeisSubscription object or NULL on failure.
*
* A gesture subscription is required for any gesture events to be delivere
d
* from the GEIS API.
*/
GEIS_API GeisSubscription geis_subscription_new(Geis geis,
GeisString name,
GeisSubscriptionFlags flags
);
/**
* Destroys a GEIS v2.0 subscription object.
*
* @param[in] subscription The subscription.
*/
GEIS_API GeisStatus geis_subscription_delete(GeisSubscription subscription)
;
/**
* Activates a subscription.
*
* @param[in] subscription The subscription.
*
* Puts the subscription into the active state. Gesture events will be
* delivered for this subscription.
*/
GEIS_API GeisStatus geis_subscription_activate(GeisSubscription subscriptio
n);
/**
* Deactivates a subscription.
*
* @param[in] subscription The subscription.
*
* Puts the subscription into the inactive state. Gesture events will not
be
* delivered for this subscription.
*/
GEIS_API GeisStatus geis_subscription_deactivate(GeisSubscription subscript
ion);
/**
* Gets the name given to a subscription when it was created.
*
* @param[in] subscription The subscription.
*/
GEIS_API GeisString geis_subscription_name(GeisSubscription subscription);
/**
* Gets the ID assigned to a subscription when it was created.
*
* @param[in] subscription The subscription.
*/
GEIS_API GeisInteger geis_subscription_id(GeisSubscription subscription);
/**
* Adds a filter to a subscription.
*
* @param[in] subscription The subscription.
* @param[in] filter The filter to be added to the subscription.
*
* Thye effect of filters are ANDed together so that, for example, a
* subscription that has a filter for 3-finger gestures and drag gestures w
ill
* produce events only for 3-finger drag gestures.
*
* The default is no filters: that is, all possible gesture events will be
* reported.
*/
GEIS_API GeisStatus geis_subscription_add_filter(GeisSubscription subscript
ion,
GeisFilter filter);
/**
* Gets an named filter from a subscription.
*
* @param[in] sub The subscription.
* @param[in] name Names the filter to retrieve.
*
* Returns the first filter with the given name or NULL if no such named fi
lter
* is found.
*/
GEIS_API GeisFilter geis_subscription_filter_by_name(GeisSubscription sub,
GeisString name)
;
/**
* Removes a filter from a subscription.
*
* @param[in] subscription The subscription.
* @param[in] filter The filter to be removed from the subscription.
*/
GEIS_API GeisStatus geis_subscription_remove_filter(GeisSubscription subscr
iption,
GeisFilter filter
);
/* @} */
/**
* @defgroup geis2_gesture Gesture Frames (GEIS v2.0)
* @{
*/
typedef struct _GeisGroup *GeisGroup;
typedef struct _GeisGroupSet *GeisGroupSet;
typedef GeisSize GeisTouchId;
typedef struct _GeisTouch *GeisTouch;
typedef struct _GeisTouchSet *GeisTouchSet;
typedef struct _GeisFrame *GeisFrame;
#define GEIS_EVENT_ATTRIBUTE_GROUPSET "group set"
#define GEIS_EVENT_ATTRIBUTE_TOUCHSET "touch set"
/**
* Gets the number of gesture groups in a groupset.
*
* @param[in] groupset The groupset.
*/
GEIS_API GeisSize geis_groupset_group_count(GeisGroupSet groupset);
/**
* Gets an indicated gesture group from a groupset.
*
* @param[in] groupset The groupset.
* @param[in] index Indicates which gesture group to retrieve.
*/
GEIS_API GeisGroup geis_groupset_group(GeisGroupSet groupset, GeisSize inde
x);
/**
* Gets the identifier of a gesture group.
*
* @param[in] group The gesture group.
*/
GEIS_API GeisInteger geis_group_id(GeisGroup group);
/**
* Gets the number of gesture frames in a gesture group.
*
* @param[in] group The gesture group.
*/
GEIS_API GeisSize geis_group_frame_count(GeisGroup group);
/**
* Gets an indicated gesture frame from a gesture group.
*
* @param[in] group The gesture group.
* @param[in] index Indicates which gesture frame to retrieve.
*/
GEIS_API GeisFrame geis_group_frame(GeisGroup group, GeisSize index);
/**
* Marks a gesture group as rejected.
*
* @param[in] group The gesture group to reject.
*/
GEIS_API void geis_group_reject(GeisGroup group);
/**
* Gets the number of touches in a touchset.
*
* @param[in] touchset The touchset,
*/
GEIS_API GeisSize geis_touchset_touch_count(GeisTouchSet touchset);
/**
* Gets an indicated touch from a touchset.
*
* @param[in] touchset The touchset.
* @param[in] index Indicates which touch to retrieve.
*/
GEIS_API GeisTouch geis_touchset_touch(GeisTouchSet touchset, GeisSize inde
x);
/**
* Gets an identified touch from a touchset.
*
* @param[in] touchset The touchset.
* @param[in] touchid Identifies a touch.
*
* Returns the identified touch, or NULL if the touchid is not in the touch
set.
*/
GEIS_API GeisTouch geis_touchset_touch_by_id(GeisTouchSet touchset,
GeisTouchId touchid);
/**
* Gets the identifier of a touch.
*
* @param[in] touch The touch.
*/
GEIS_API GeisTouchId geis_touch_id(GeisTouch touch);
/**
* Gets the number of attrs associated with a touch.
*
* @param[in] touch The touch.
*/
GEIS_API GeisSize geis_touch_attr_count(GeisTouch touch);
/**
* Gets an indicated attr from a touch.
*
* @param[in] touch The touch.
* @param[in] index Indicates which attr to retrieve.
*/
GEIS_API GeisAttr geis_touch_attr(GeisTouch touch, GeisSize index);
/**
* Gets a named attr from a touch.
*
* @param[in] touch The touch.
* @param[in] name Names the attr to retrieve.
*
* @returns the named attr if it is present, NULL otherwise.
*/
GEIS_API GeisAttr geis_touch_attr_by_name(GeisTouch touch, GeisString name)
;
/**
* Gets the identifier of a gesture frame.
*
* @param[in] frame the gesture frame.
*/
GEIS_API GeisGestureId geis_frame_id(GeisFrame frame);
/**
* Indicates if a gesture frame belongs to a gesture class.
*
* @param[in] frame The gesture frame.
* @param[in] gesture_class The gesture class.
*
* @returns true if the gesture can currently be classified by the @p
* gesture_class, false otherwise.
*/
GEIS_API GeisBoolean geis_frame_is_class(GeisFrame frame,
GeisGestureClass gesture_class);
/**
* Gets the number of attrs associated with a gesture frame.
*
* @param[in] frame The gesture frame.
*/
GEIS_API GeisSize geis_frame_attr_count(GeisFrame frame);
/**
* Gets an indicated attr from a gesture frame.
*
* @param[in] frame The gesture frame.
* @param[in] index Indicates which attr to retrieve.
*/
GEIS_API GeisAttr geis_frame_attr(GeisFrame frame, GeisSize index);
/**
* Gets a named attr from a gesture frame.
*
* @param[in] frame The gesture frame.
* @param[in] name Names the attr to retrieve.
*
* @returns the named attr if it is present, NULL otherwise.
*/
GEIS_API GeisAttr geis_frame_attr_by_name(GeisFrame frame, GeisString name)
;
/**
* Gets the current transform matrix of a gesture.
*
* @param[in] frame The gesture frame.
*/
GEIS_API GeisFloat *geis_frame_matrix(GeisFrame frame);
/**
* Gets the number of touches making up a gesture for the frame.
*
* @param[in] frame The gesture frame.
*/
GEIS_API GeisSize geis_frame_touchid_count(GeisFrame frame);
/**
* Gets the ID of the indicated touch within the gesture frame.
*
* @param[in] frame The gesture frame.
* @param[in] index Indicates which touch ID to retrieve.
*/
GEIS_API GeisTouchId geis_frame_touchid(GeisFrame frame, GeisSize index);
/**
* Marks a gesture as rejected.
*
* @param[in] gesture_id Identifies the gesture.
*/
GEIS_API void geis_gesture_reject(GeisGestureId gestureid);
/* @} */
#ifdef __cplusplus #ifdef __cplusplus
} // extern "C" } /* extern "C" */
#endif #endif
#endif /* GEIS_GEIS_H_ */ #endif /* GEIS_GEIS_H_ */
 End of changes. 15 change blocks. 
6 lines changed or deleted 1153 lines changed or added


 geisimpl.h   geisimpl.h 
skipping to change at line 61 skipping to change at line 61
#define GEIS_LOCAL #define GEIS_LOCAL
#endif /* GEIS_BUILDING_DSO */ #endif /* GEIS_BUILDING_DSO */
/** /**
* Portability types * Portability types
*/ */
typedef size_t GeisSize; typedef size_t GeisSize;
typedef uint32_t GeisBoolean; typedef uint32_t GeisBoolean;
typedef int32_t GeisInteger; typedef int32_t GeisInteger;
typedef float GeisFloat; typedef float GeisFloat;
typedef void* GeisPointer;
typedef const char *GeisString; typedef const char *GeisString;
/** /**
* @brief Magic for constructing geis win_type values. * @brief Magic for constructing geis win_type values.
*/ */
static inline uint32_t _geis_win_type_str(const char tag[5]) static inline uint32_t _geis_win_type_str(const char tag[5])
{ return (((((tag[3] << 8 ) | tag[2]) << 8) | tag[1]) << 8) | tag[0]; } { return (((((tag[3] << 8 ) | tag[2]) << 8) | tag[1]) << 8) | tag[0]; }
#define geis_win_type_str(tag) _geis_win_type_str(#tag) #define geis_win_type_str(tag) _geis_win_type_str(#tag)
 End of changes. 1 change blocks. 
0 lines changed or deleted 1 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/