Introduction to the Advanced GEIS Interface
The advanced GEIS interface is designed around the idea that you can create filters to limit the kinds of gestures received and combine those filters into subscriptions that interact with the gesture recognizer to deliver gesture events.
The normal flow for using the advanced interface is as follows.
- create a Geis object
- create a GeisSubscription object on the Geis object
- create and add one or more GeisFilter to the GeisSubscription
- activate the GeisSubscription
- wait for and process a series of GeisEvent
An example of advanced API usage
This is an example of using the advanced (GEIS v2) API. The full source code for this example (including details missing here) is included in the source distribution of geis.
Please note that these examples omit all of the error checking for expository purposes only.
First, a function to create the filters for a subscription. the filters can not be created until the gesture recognition engine initialization is complete, since otherwise the expected types of the gesture attributes on which to filter are not known by the interface.
An empty filter is created. An empty filter means all input devices, all gestures, all regions. For the purpose of this example, we want just 2-touch gestures, so we need to add a term to the filter specifying only those gestures with two touches.
{
NULL);
{
fprintf(stderr, "error adding filter\n");
}
Selects a subset of possible gestures in a subscription.
Represents an instance of the gesture recognition engine.
A gesture recognition subscription.
GeisStatus
Errors returned from calls.
Definition: geis.h:73
@ GEIS_STATUS_SUCCESS
normal successful completion
Definition: geis.h:74
@ GEIS_FILTER_CLASS
Filters on gesture class and gesture attributes.
Definition: geis.h:1714
@ GEIS_FILTER_OP_EQ
Compares for equality.
Definition: geis.h:1724
GeisStatus geis_subscription_add_filter(GeisSubscription subscription, GeisFilter filter)
Adds a filter to a subscription.
GeisFilter geis_filter_new(Geis geis, GeisString name)
Creates a new, empty filter.
GEIS_VARARG GeisStatus geis_filter_add_term(GeisFilter filter, GeisFilterFacility facility,...)
Adds a term to a filter.
}
In the main fucntion, the API instance is created. We tell it to report input devices and gesture classes.
NULL);
#define GEIS_INIT_TRACK_DEVICES
Tells GEIS to send input device events.
Definition: geis.h:566
#define GEIS_INIT_TRACK_GESTURE_CLASSES
Tells GEIS to send gesture class events.
Definition: geis.h:567
GEIS_VARARG Geis geis_new(GeisString init_arg_name,...)
Initializes an instance of the GEIS v2.0 API.
For the event loop processing, we're going to need the event fd (this is assuming a Unix implementation of GEIS, other platforms may have a different event indicator).
GeisStatus geis_get_configuration(Geis geis, GeisString configuration_item_name, void *configuration_item_value)
Gets a feature configuration value.
#define GEIS_CONFIGURATION_FD
Gets a Unix file descriptor that will signal the availablility of GEIS events for processing.
Definition: geis.h:714
A subscription object is created. We want gesture continuations.
GeisSubscription geis_subscription_new(Geis geis, GeisString name, GeisSubscriptionFlags flags)
Creates a new subscription.
@ GEIS_SUBSCRIPTION_CONT
The gesture engine will return gesture continuations, in which the class of a recognized gestire may ...
Definition: geis.h:1845
The application's main event loop is run until a read is indicated as available on the event fd, at which point the GEIS event loop is pumped.
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.
The events are handled and the event loop pumped until it's empty.
{
{
case GEIS_EVENT_INIT_COMPLETE:
target_subscription(geis, subscription);
break;
case GEIS_EVENT_DEVICE_AVAILABLE:
case GEIS_EVENT_DEVICE_UNAVAILABLE:
dump_device_event(event);
break;
case GEIS_EVENT_GESTURE_BEGIN:
case GEIS_EVENT_GESTURE_UPDATE:
case GEIS_EVENT_GESTURE_END:
dump_gesture_event(event);
break;
default:
break;
}
@ GEIS_STATUS_CONTINUE
normal successful completion with data still remaining
Definition: geis.h:75
void geis_event_delete(GeisEvent event)
Destroys a GeisEvent.
GeisEventType geis_event_type(GeisEvent event)
Gets the type of the event.
GeisStatus geis_subscription_activate(GeisSubscription subscription)
Activates a subscription.
Finally, the API objects are cleaned up.
GeisStatus geis_delete(Geis geis)
Cleans up an instance of the GEIS v2.0 API.
GeisStatus geis_subscription_delete(GeisSubscription subscription)
Destroys a GEIS v2.0 subscription object.
Examining Devices
{
GeisAttr attr;
GeisSize i;
printf("device %02d \"%s\"\n",
{
}
A gesture-capable input device.
GeisAttr geis_event_attr_by_name(GeisEvent event, GeisString attr_name)
Gets a named attribute from the event.
GeisPointer geis_attr_value_to_pointer(GeisAttr attr)
Gets the value of an attribute as a GeisPointer.
GeisAttr geis_device_attr(GeisDevice device, GeisSize index)
Gets the indicated attribute of the device.
#define GEIS_EVENT_ATTRIBUTE_DEVICE
The event attribute containing a pointer to a GeisDevice.
Definition: geis.h:1273
GeisInteger geis_device_id(GeisDevice device)
Gets the system identifier of the iput device.
GeisSize geis_device_attr_count(GeisDevice device)
Gets the number of attributes of the device.
GeisString geis_device_name(GeisDevice device)
Gets the name of the input device.
}