Loading...
Searching...
No Matches
Using The Advanced Interface

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

1. create a Geis object
2. create a GeisSubscription object on the Geis object
3. create and add one or more GeisFilter to the GeisSubscription
4. activate the GeisSubscription
5. 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.

target_subscription(Geis geis, GeisSubscription subscription)
{
GeisStatus status;
GeisFilter filter = geis_filter_new(geis, "filter");
geis_filter_add_term(filter,
GEIS_FILTER_CLASS,
GEIS_GESTURE_ATTRIBUTE_TOUCHES, GEIS_FILTER_OP_EQ, 2,
NULL);
status = geis_subscription_add_filter(subscription, filter);
if (status != GEIS_STATUS_SUCCESS)
{
fprintf(stderr, "error adding filter\n");
}
GeisFilter
Selects a subset of possible gestures in a subscription.
Geis
Represents an instance of the gesture recognition engine.
GeisSubscription
A gesture recognition subscription.
GeisStatus
GeisStatus
Errors returned from calls.
Definition geis.h:73
GEIS_STATUS_SUCCESS
@ GEIS_STATUS_SUCCESS
normal successful completion
Definition geis.h:74
GEIS_FILTER_CLASS
@ GEIS_FILTER_CLASS
Filters on gesture class and gesture attributes.
Definition geis.h:1714
GEIS_FILTER_OP_EQ
@ GEIS_FILTER_OP_EQ
Compares for equality.
Definition geis.h:1724
}

In the main fucntion, the API instance is created. We tell it to report input devices and gesture classes.

geis = geis_new(GEIS_INIT_TRACK_DEVICES,
GEIS_INIT_TRACK_GESTURE_CLASSES,
NULL);
GEIS_INIT_TRACK_DEVICES
#define GEIS_INIT_TRACK_DEVICES
Tells GEIS to send input device events.
Definition geis.h:566
GEIS_INIT_TRACK_GESTURE_CLASSES
#define GEIS_INIT_TRACK_GESTURE_CLASSES
Tells GEIS to send gesture class events.
Definition geis.h:567

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

geis_get_configuration(geis, GEIS_CONFIGURATION_FD, &fd);
geis_get_configuration
GeisStatus geis_get_configuration(Geis geis, GeisString configuration_item_name, void *configuration_item_value)
Gets a feature configuration value.
GEIS_CONFIGURATION_FD
#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.

subscription = geis_subscription_new(geis, "example", GEIS_SUBSCRIPTION_CONT);
GEIS_SUBSCRIPTION_CONT
@ 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.

status = geis_dispatch_events(geis);
status = geis_next_event(geis, &event);
geis_dispatch_events
GeisStatus geis_dispatch_events(Geis geis)
Pumps the GEIS event loop.
geis_next_event
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.

while (status == GEIS_STATUS_CONTINUE || status == GEIS_STATUS_SUCCESS)
{
switch (geis_event_type(event))
{
case GEIS_EVENT_INIT_COMPLETE:
target_subscription(geis, subscription);
status = geis_subscription_activate(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_event_delete(event);
status = geis_next_event(geis, &event);
GEIS_STATUS_CONTINUE
@ GEIS_STATUS_CONTINUE
normal successful completion with data still remaining
Definition geis.h:75

Finally, the API objects are cleaned up.

geis_subscription_delete(subscription);
geis_delete(geis);

## Examining Devices

dump_device_event(GeisEvent event)
{
GeisDevice device;
GeisAttr attr;
GeisSize i;
attr = geis_event_attr_by_name(event, GEIS_EVENT_ATTRIBUTE_DEVICE);
device = geis_attr_value_to_pointer(attr);
printf("device %02d \"%s\"\n",
geis_device_id(device), geis_device_name(device));
for (i = 0; i < geis_device_attr_count(device); ++i)
{
print_attr(geis_device_attr(device, i));
}
GeisDevice
A gesture-capable input device.
GeisEvent
A generic GEIS event.
geis_attr_value_to_pointer
GeisPointer geis_attr_value_to_pointer(GeisAttr attr)
Gets the value of an attribute as a GeisPointer.
GEIS_EVENT_ATTRIBUTE_DEVICE
#define GEIS_EVENT_ATTRIBUTE_DEVICE
The event attribute containing a pointer to a GeisDevice.
Definition geis.h:1273
}