doc/gesture_recognition_doc.h

   1 /*
   2  * gesture
   3  *
   4  * Copyright (c) 2014 Samsung Electronics Co., Ltd.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20 /**
  21  * @ingroup             CAPI_CONTEXT_FRAMEWORK
  22  * @defgroup    CAPI_CONTEXT_GESTURE_MODULE Gesture Recognition
  23  *
  24  * @brief               The gesture recognition API allows applications to be notified and
  25  *                              react when the user performs a gesture.
  26  *
  27  * @section             CAPI_CONTEXT_GESTURE_MODULE_HEADER Required Header
  28  *                              \#include <gesture_recognition.h>
  29  *
  30  * @section             CAPI_CONTEXT_GESTURE_MODULE_OVERVIEW Overview
  31  *
  32  *
  33  * The gesture recognition API allows to register callback functions to be called
  34  * when the user performs meaningful gestures listed in #gesture_type_e, for example,
  35  * shaking the device.
  36  *
  37  * Regardless of the gesture types,
  38  * the overall process of using the gesture recognition API is as follows.
  39  *
  40  * If necessary, applications can check whether a gesture type is supported in the current device in advance.
  41  * Note that, some gestures may not be supported in some devices, if the devices do not have necessary sensors.
  42
  43  \code
  44         bool supported = false;
  45         gesture_is_supported(GESTURE_SHAKE, &supported);
  46
  47         if (!supported) {
  48                 // Not supported in the current device.
  49         }
  50  \endcode
  51
  52  * If the gesture type is supported, to use the recognition engine,
  53  * an @c handle for the gesture recognition needs to be initialized first.
  54
  55  \code
  56         gesture_h handle;
  57
  58         result = gesture_create(&handle);
  59
  60         if (result != GESTURE_ERROR_NONE) {
  61                 // An error occurred.
  62         }
  63  \endcode
  64
  65  * With the @c handle initialized, a callback function,
  66  * which will be called when a specified gesture is detected,
  67  * is registered by using gesture_start_recognition().
  68
  69  \code
  70         result = gesture_start_recognition(handle, GESTURE_SHAKE, GESTURE_OPTION_DEFAULT, gesture_cb, NULL);
  71
  72         if (result != GESTURE_ERROR_NONE) {
  73                 // An error occurred. Do necessary error handling here.
  74         }
  75  \endcode
  76
  77  * Then the callback function @c gesture_cb will be called whenever the shake gesture is detected.
  78  *
  79  * Note that, calling gesture_start_recognition() twice on the same handle returns #GESTURE_ERROR_ALREADY_STARTED.
  80  * If it needs to recognize another gesture using the same handle,
  81  * the started recognition session should be stopped and restarted with the new gesture type.
  82  * Otherwise, the application needs to created multiple handles, one handle for each gesture needed.
  83  *
  84  * An example callback function is as follows.
  85
  86  \code
  87         void gesture_cb(gesture_type_e type, const gesture_data_h data, double timestamp, gesture_error_e error, void *user_data)
  88         {
  89                 int result;
  90                 gesture_event_e event;
  91
  92                 if (error != GESTURE_ERROR_NONE) {
  93                         // An error occurred. Do necessary error handling here.
  94                         return;
  95                 }
  96
  97                 if (type == GESTURE_SHAKE) {
  98                         // More than one gestures can be started using the same callback function.
  99
 100                         result = gesture_get_event(data, &event);
 101
 102                         if (result != GESTURE_ERROR_NONE) {
 103                                 // An error occurred. Do necessary error handling here.
 104                                 return;
 105                         }
 106
 107                         if (event == GESTURE_SHAKE_DETECTED) {
 108                                 // Shake gesture is started
 109
 110                         } else if (event == GESTURE_SHAKE_FINISHED) {
 111                                 // Shake gesture is stopped
 112                         }
 113                 }
 114         }
 115  \endcode
 116
 117  * As we started gesture recognition with #GESTURE_SHAKE,
 118  * gesture_get_event() returns either #GESTURE_SHAKE_DETECTED or #GESTURE_SHAKE_FINISHED
 119  * as it has two different states, the gesture is started, or finished.
 120  * Most of the gesture types, however, simply provide #GESTURE_EVENT_DETECTED.
 121  * In such cases, #GESTURE_EVENT_NONE may not be delivered at all.
 122  *
 123  * If #GESTURE_TILT is started, within the callback function,
 124  * gesture_get_tilt() can be used to extract the tilting degrees.
 125  *
 126  * Finally, if the application does not need to be notified the gesture event,
 127  * it can be stopped as follows.
 128
 129  \code
 130         gesture_stop_recognition(handle);
 131
 132         // If the handle will not be used anymore, its resources needs be released explicitly.
 133         gesture_release(handle);
 134  \endcode
 135
 136  * @section             CAPI_CONTEXT_GESTURE_MODULE_FEATURE Related Features
 137  * This API is related with the following features:\n
 138  * - http://tizen.org/feature/sensor.gesture_recognition\n
 139  * - http://tizen.org/feature/sensor.wrist_up
 140  *
 141  * It is recommended to design feature related code in your application for reliability.\n
 142  *
 143  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application.\n
 144  *
 145  * 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.\n
 146  *
 147  * More details on featuring your application can be found from <a href="https://developer.tizen.org/development/tizen-studio/native-tools/configuring-your-app/manifest-text-editor#feature"><b>Feature Element</b>.</a>
 148  *
 149  */