Tizen Native API
5.5
|
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:
- http://tizen.org/feature/sensor.gesture_recognition
- http://tizen.org/feature/sensor.wrist_up
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
typedef struct _gesture_handle_s* gesture_h |
The gesture recognizer controlling handle.
- Since :
- 2.3
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
- Parameters:
-
[in] gesture Gesture type detected [in] data Detailed information of the detected gesture.
gesture_get_event() or gesture_get_tilt() can be used to extract the information fromdata
.[in] timestamp The time when the gesture is detected. Epoch time in seconds. [in] error An 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_data The 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
- Enumerator:
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
- Enumerator:
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
enum gesture_type_e |
Enumeration for gesture types.
- Since :
- 2.3
- Enumerator:
Function Documentation
int gesture_create | ( | gesture_h * | handle | ) |
Initializes a gesture handle.
- Since :
- 2.3
- Parameters:
-
[out] handle Gesture handle to be initialized
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_OPERATION_FAILED Operation 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
- Parameters:
-
[in] data Gesture data received through a callback function [out] event Gesture event data
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_OPERATION_FAILED Operation 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
- Parameters:
-
[in] data Tilt gesture data received through a callback function [out] x Tilting degree on X-axis [out] y Tilting degree on Y-axis
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_OPERATION_FAILED Operation 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
- Parameters:
-
[in] gesture Gesture type to be checked [out] supported true
if the gesture is recognizable in the current device,
false
otherwise
- Returns:
0
if thegesture
is supported, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Supported GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED The gesture
is not supportedGESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error GESTURE_ERROR_PERMISSION_DENIED Does not have permission to use this
int gesture_release | ( | gesture_h | handle | ) |
Releases the resources occupied by the gesture handle.
- Since :
- 2.3
- Parameters:
-
[in] handle Gesture handle to be released
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_OPERATION_FAILED Operation 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
- Parameters:
-
[in] handle Gesture handle to be used to control the gesture event [in] gesture Gesture type to be monitored [in] option Detection option [in] callback Callback function to receive gesture events [in] user_data User data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_ALREADY_STARTED The handle
is being used alreadyGESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error GESTURE_ERROR_PERMISSION_DENIED Does 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
- Parameters:
-
[in] handle Gesture handle to release its callback function registered
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
GESTURE_ERROR_NONE Successful GESTURE_ERROR_INVALID_PARAMETER Invalid parameter used GESTURE_ERROR_NOT_SUPPORTED Gesture recognition is not supported GESTURE_ERROR_NOT_STARTED Nothing is started using the handle
GESTURE_ERROR_OPERATION_FAILED Operation failed because of a system error