Tizen Native API  4.0
Functions | Typedefs
Gesture Recognition
Context

The gesture recognition API allows applications to be notified and react when the user performs a gesture.

Required Header

#include <gesture_recognition.h>

Overview

The gesture recognition API allows to register callback functions to be called when the user performs meaningful gestures listed in gesture_type_e, for example, shaking the device.

Regardless of the gesture types, the overall process of using the gesture recognition API is as follows.

If necessary, applications can check whether a gesture type is supported in the current device in advance. Note that, some gestures may not be supported in some devices, if the devices do not have necessary sensors.

    bool supported = false;
    gesture_is_supported(GESTURE_SHAKE, &supported);

    if (!supported) {
        // Not supported in the current device.
    }

If the gesture type is supported, to use the recognition engine, an handle for the gesture recognition needs to be initialized first.

    gesture_h handle;

    result = gesture_create(&handle);

    if (result != GESTURE_ERROR_NONE) {
        // An error occurred.
    }

With the handle initialized, a callback function, which will be called when a specified gesture is detected, is registered by using gesture_start_recognition().

    result = gesture_start_recognition(handle, GESTURE_SHAKE, GESTURE_OPTION_DEFAULT, gesture_cb, NULL);

    if (result != GESTURE_ERROR_NONE) {
        // An error occurred. Do necessary error handling here.
    }

Then the callback function gesture_cb will be called whenever the shake gesture is detected.

Note that, calling gesture_start_recognition() twice on the same handle returns GESTURE_ERROR_ALREADY_STARTED. If it needs to recognize another gesture using the same handle, the started recognition session should be stopped and restarted with the new gesture type. Otherwise, the application needs to created multiple handles, one handle for each gesture needed.

An example callback function is as follows.

    void gesture_cb(gesture_type_e type, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
    {
        int result;
        gesture_event_e event;

        if (error != GESTURE_ERROR_NONE) {
            // An error occurred. Do necessary error handling here.
            return;
        }

        if (type == GESTURE_SHAKE) {
            // More than one gestures can be started using the same callback function.

            result = gesture_get_event(data, &event);

            if (result != GESTURE_ERROR_NONE) {
                // An error occurred. Do necessary error handling here.
                return;
            }

            if (event == GESTURE_SHAKE_DETECTED) {
                // Shake gesture is started

            } else if (event == GESTURE_SHAKE_FINISHED) {
                // Shake gesture is stopped
            }
        }
    }

As we started gesture recognition with GESTURE_SHAKE, gesture_get_event() returns either GESTURE_SHAKE_DETECTED or GESTURE_SHAKE_FINISHED as it has two different states, the gesture is started, or finished. Most of the gesture types, however, simply provide GESTURE_EVENT_DETECTED. In such cases, GESTURE_EVENT_NONE may not be delivered at all.

If GESTURE_TILT is started, within the callback function, gesture_get_tilt() can be used to extract the tilting degrees.

Finally, if the application does not need to be notified the gesture event, it can be stopped as follows.

    gesture_stop_recognition(handle);

    // If the handle will not be used anymore, its resources needs be released explicitly.
    gesture_release(handle);

Related Features

This API is related with the following features:

It is recommended to design feature related code in your application for reliability.

You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.

To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.

More details on featuring your application can be found from Feature Element.

Functions

int gesture_is_supported (gesture_type_e gesture, bool *supported)
 Check whether the gesture is supported or not.
int gesture_create (gesture_h *handle)
 Initializes a gesture handle.
int gesture_release (gesture_h handle)
 Releases the resources occupied by the gesture handle.
int gesture_start_recognition (gesture_h handle, gesture_type_e gesture, gesture_option_e option, gesture_recognition_cb callback, void *user_data)
 Starts to recognize a gesture.
int gesture_stop_recognition (gesture_h handle)
 Stops recognizing the gesture registered to the gesture handle.
int gesture_get_event (const gesture_data_h data, gesture_event_e *event)
 Gets the gesture event from the gesture data received.
int gesture_get_tilt (const gesture_data_h data, int *x, int *y)
 Gets the tilting degrees from GESTURE_TILT data received.

Typedefs

typedef struct _gesture_handle_s * gesture_h
 The gesture recognizer controlling handle.
typedef struct _gesture_data_s * gesture_data_h
 Delivery through gesture_recognition_cb() of gesture data handle.
typedef void(* gesture_recognition_cb )(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
 Called when a gesture is detected.

Typedef Documentation

typedef struct _gesture_data_s* gesture_data_h

Delivery through gesture_recognition_cb() of gesture data handle.

Since :
2.3.1
typedef struct _gesture_handle_s* gesture_h

The gesture recognizer controlling handle.

Since :
2.3.1
typedef void(* gesture_recognition_cb)(gesture_type_e gesture, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)

Called when a gesture is detected.

Since :
2.3.1
Parameters:
[in]gestureGesture type detected
[in]dataDetailed information of the detected gesture.
gesture_get_event() or gesture_get_tilt() can be used to extract the information from data.
[in]timestampThe time when the gesture is detected. Epoch time in seconds.
[in]errorAn error value. It can be one of the following error values:
GESTURE_ERROR_NONE, if the operation succeeded.
GESTURE_ERROR_NOT_SUPPORTED, if the gesture is not supported in the current profile.
GESTURE_ERROR_OPERATION_FAILED, if the operation failed because of a system error.
GESTURE_ERROR_PERMISSION_DENIED, if the application has no permission to use this.
[in]user_dataThe user data had passed to gesture_start_recognition()
Precondition:
gesture_start_recognition()

Enumeration Type Documentation

enum gesture_error_e

Enumeration for error codes.

Since :
2.3.1
Enumerator:
GESTURE_ERROR_NONE 

Successful

GESTURE_ERROR_INVALID_PARAMETER 

Invalid function parameter

GESTURE_ERROR_INVALID_OPERATION 

Function not implemented

GESTURE_ERROR_OUT_OF_MEMORY 

Out of memory

GESTURE_ERROR_PERMISSION_DENIED 

Permission denied

GESTURE_ERROR_NOT_SUPPORTED 

Not supported

GESTURE_ERROR_ALREADY_STARTED 

Recognition is already started

GESTURE_ERROR_NOT_STARTED 

Recognition is not started

GESTURE_ERROR_OPERATION_FAILED 

Operation failed because of a system error

enum gesture_event_e

Enumeration for gesture event types.

With regards to type of the gesture, gesture_get_event() returns one of the followings.

Since :
2.3.1
Enumerator:
GESTURE_EVENT_NONE 

Detected nothing

GESTURE_EVENT_DETECTED 

Detected the gesture

GESTURE_SHAKE_DETECTED 

Shake gesture started

GESTURE_SHAKE_FINISHED 

Shake gesture stopped

GESTURE_SNAP_X_NEGATIVE 

Detected -X snap

GESTURE_SNAP_X_POSITIVE 

Detected +X snap

GESTURE_SNAP_Y_NEGATIVE 

Detected -Y snap

GESTURE_SNAP_Y_POSITIVE 

Detected +Y snap

GESTURE_SNAP_Z_NEGATIVE 

Detected -Z snap

GESTURE_SNAP_Z_POSITIVE 

Detected +Z snap

enum gesture_option_e

Enumeration for gesture recognition option.

If the default option is used, the system tries to reduce power consumption. For example, the recognition engine may stop detecting gestures if the display is turned off. Using GESTURE_OPTION_ALWAYS_ON disables such power-saving functionalities.

Since :
2.3.1
Enumerator:
GESTURE_OPTION_DEFAULT 

Running in the default setting

GESTURE_OPTION_ALWAYS_ON 

Trying to detect gestures always

enum gesture_type_e

Enumeration for gesture types.

Since :
2.3.1
Enumerator:
GESTURE_DOUBLE_TAP 

The mobile device is tapped twice

GESTURE_MOVE_TO_EAR 

The mobile device is moved near to an ear

GESTURE_NO_MOVE 

The mobile device is being stopped for a while

GESTURE_PICK_UP 

The mobile device is picked up

GESTURE_SHAKE 

The mobile device is quickly moved back and forth

GESTURE_SNAP 

The mobile device is moved along an axis and back

GESTURE_TILT 

The mobile device is tilted

GESTURE_TURN_FACE_DOWN 

The mobile device is flipped from face to back

GESTURE_WRIST_UP 

The wearable device is moved and faced up

Function Documentation

int gesture_create ( gesture_h *  handle)

Initializes a gesture handle.

Since :
2.3.1
Parameters:
[out]handleGesture handle to be initialized
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error, e.g., out of memory
See also:
gesture_release()
int gesture_get_event ( const gesture_data_h  data,
gesture_event_e *  event 
)

Gets the gesture event from the gesture data received.

Since :
2.3.1
Parameters:
[in]dataGesture data received through a callback function
[out]eventGesture event data
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
int gesture_get_tilt ( const gesture_data_h  data,
int *  x,
int *  y 
)

Gets the tilting degrees from GESTURE_TILT data received.

Since :
2.3.1
Parameters:
[in]dataTilt gesture data received through a callback function
[out]xTilting degree on X-axis
[out]yTilting degree on Y-axis
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
int gesture_is_supported ( gesture_type_e  gesture,
bool *  supported 
)

Check whether the gesture is supported or not.

Check if the given gesture type is supported in the current device.

Since :
2.3.1
Parameters:
[in]gestureGesture type to be checked
[out]supportedtrue if the gesture is recognizable in the current device,
false otherwise
Returns:
0 if the gesture is supported, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESupported
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDThe gesture is not supported
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
GESTURE_ERROR_PERMISSION_DENIEDDoes not have permission to use this
int gesture_release ( gesture_h  handle)

Releases the resources occupied by the gesture handle.

Since :
2.3.1
Parameters:
[in]handleGesture handle to be released
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
Precondition:
gesture_create()
int gesture_start_recognition ( gesture_h  handle,
gesture_type_e  gesture,
gesture_option_e  option,
gesture_recognition_cb  callback,
void *  user_data 
)

Starts to recognize a gesture.

Sets a callback function to be invoked when the gesture is detected, and starts to monitor occurrences of the gesture.

Since :
2.3.1
Parameters:
[in]handleGesture handle to be used to control the gesture event
[in]gestureGesture type to be monitored
[in]optionDetection option
[in]callbackCallback function to receive gesture events
[in]user_dataUser data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_ALREADY_STARTEDThe handle is being used already
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error
GESTURE_ERROR_PERMISSION_DENIEDDoes not have permission to use this
Precondition:
gesture_create()
Postcondition:
gesture_recognition_cb()
See also:
gesture_stop_recognition()
int gesture_stop_recognition ( gesture_h  handle)

Stops recognizing the gesture registered to the gesture handle.

Since :
2.3.1
Parameters:
[in]handleGesture handle to release its callback function registered
Returns:
0 on success, otherwise a negative error value
Return values:
GESTURE_ERROR_NONESuccessful
GESTURE_ERROR_INVALID_PARAMETERInvalid parameter used
GESTURE_ERROR_NOT_SUPPORTEDGesture recognition is not supported
GESTURE_ERROR_NOT_STARTEDNothing is started using the handle
GESTURE_ERROR_OPERATION_FAILEDOperation failed because of a system error