inputmethod/include/inputmethod_device_event.h

   1 /*
   2  * Copyright (c) 2016-2021 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_UIX_INPUTMETHOD_DEVICE_EVENT_H__
  18 #define __TIZEN_UIX_INPUTMETHOD_DEVICE_EVENT_H__
  19
  20 /**
  21  * @file inputmethod_device_event.h
  22  * @brief This file contains definitions for unconventional input device events.
  23  */
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 /**
  30  * @addtogroup CAPI_UIX_INPUTMETHOD_MODULE
  31  * @{
  32  */
  33
  34  /**
  35  * @brief The handle to retrieve unconventional input device specific event data.
  36  *
  37  * @since_tizen @if WEARABLE 3.0 @endif
  38  *
  39  * @see ime_event_set_process_input_device_event_cb()
  40  */
  41 typedef void *ime_input_device_event_h;
  42
  43 /**
  44  * @brief Enumeration of unconventional input devices.
  45  *
  46  * @since_tizen @if WEARABLE 3.0 @endif
  47  *
  48  * @see ime_event_set_process_input_device_event_cb()
  49  */
  50 typedef enum {
  51     IME_INPUT_DEVICE_TYPE_UNKNOWN, /**< Undefined unconventional input device */
  52     IME_INPUT_DEVICE_TYPE_ROTARY, /**< A rotary input device such as bezel that can be found on a wearable device */
  53 } ime_input_device_type_e;
  54
  55 /**
  56  * @brief Enumeration of directions for rotary input device's rotation event.
  57  *
  58  * @since_tizen @if WEARABLE 3.0 @endif
  59  *
  60  * @see ime_input_device_rotary_get_direction()
  61  */
  62 typedef enum
  63 {
  64     IME_INPUT_DEVICE_ROTARY_DIRECTION_CLOCKWISE, /**< Rotary is rotated clockwise direction */
  65     IME_INPUT_DEVICE_ROTARY_DIRECTION_COUNTER_CLOCKWISE /**< Rotary is rotated counter clockwise direction */
  66 } ime_input_device_rotary_direction_e;
  67
  68 /**
  69  * @brief Called when the input event is received from an unconventional input device that does not generate key events.
  70  *
  71  * @details This function processes the input event before an associated text input UI control does.
  72  *
  73  * @since_tizen @if WEARABLE 3.0 @endif
  74  *
  75  * @remarks @a device_type contains the information what kind of unconventional input device generated the given event,
  76  * and the handle @a device_event is used for obtaining device-specific input device event data.
  77  * @a device_event should not be released.
  78  *
  79  * @param[in] device_type The unconventional input device type
  80  * @param[in] device_event The handle for device_type specific input device event
  81  * @param[in] user_data User data to be passed to the callback function
  82  *
  83  * @pre The callback can be registered using ime_event_set_input_device_event_cb() function.
  84  *
  85  * @see ime_event_set_process_input_device_event_cb()
  86  */
  87 typedef void(*ime_process_input_device_event_cb)(ime_input_device_type_e device_type, ime_input_device_event_h device_event, void *user_data);
  88
  89 /**
  90  * @brief Sets @c process_input_device_event event callback function.
  91  *
  92  * @since_tizen @if WEARABLE 3.0 @endif
  93  *
  94  * @privlevel public
  95  *
  96  * @privilege %http://tizen.org/privilege/ime
  97  *
  98  * @remarks The ime_process_input_device_event_cb() callback function is called when the event
  99  * is received from unconventional input devices that needs to be handled by IMEs.
 100  *
 101  * @param[in] callback_func @c inputmethod_process_input_device_event_cb callback function
 102  * @param[in] user_data User data to be passed to the callback function
 103  *
 104  * @return 0 on success, otherwise a negative error value
 105  * @retval #IME_ERROR_NONE No error
 106  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 107  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 108  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 109  *
 110  * @post The ime_run() function should be called to start to run IME application's main loop.
 111  *
 112  * @see ime_process_input_device_event_cb()
 113  * @see ime_event_unset_process_input_device_event_cb()
 114  * @see ime_run()
 115  *
 116  * @code
 117  static void inputmethod_create_cb(void *user_data);
 118  static void inputmethod_terminate_cb(void *user_data);
 119  static void inputmethod_show_cb(int context_id, ime_context_h context, void *user_data);
 120  static void inputmethod_hide_cb(int context_id, void *user_data);
 121
 122  static void inputmethod_process_input_device_event_cb(ime_input_device_type_e device_type, ime_input_device_event_h device_event, void *user_data)
 123  {
 124     if (device_type == IME_INPUT_DEVICE_TYPE_ROTARY) {
 125         dlog_print(DLOG_INFO, "INPUTMETHOD", "Input device type is rotary\n");
 126     }
 127  }
 128
 129  void ime_app_main(int argc, char **argv)
 130  {
 131     ime_callback_s basic_callback = {
 132         inputmethod_create_cb,
 133         inputmethod_terminate_cb,
 134         inputmethod_show_cb,
 135         inputmethod_hide_cb,
 136     };
 137
 138     ime_event_set_process_input_device_event_cb(inputmethod_process_input_device_event_cb, NULL);
 139
 140     ime_run(&basic_callback, NULL);
 141  }
 142  * @endcode
 143  */
 144
 145 int ime_event_set_process_input_device_event_cb(ime_process_input_device_event_cb callback_func, void *user_data);
 146
 147 /**
 148  * @brief Unsets @c process_input_device_event event callback function.
 149  *
 150  * @since_tizen @if WEARABLE 3.0 @endif
 151  *
 152  * @privlevel public
 153  *
 154  * @privilege %http://tizen.org/privilege/ime
 155  *
 156  * @remarks The ime_process_input_device_event_cb() callback function is called when the event
 157  * is received from unconventional input devices that needs to be handled by IMEs.
 158  *
 159  * @return 0 on success, otherwise a negative error value
 160  * @retval #IME_ERROR_NONE No error
 161  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 162  * @retval #IME_ERROR_OPERATION_FAILED Operation failed
 163  *
 164  * @see ime_process_input_device_event_cb()
 165  * @see ime_event_set_process_input_device_event_cb()
 166  */
 167 int ime_event_unset_process_input_device_event_cb(void);
 168
 169 /**
 170  * @brief Gets the direction of the rotary input device event
 171  *
 172  * If the device_type parameter of the ime_process_input_device_event_cb() function indicates
 173  * the current input device type is #IME_INPUT_DEVICE_TYPE_ROTARY, then the device_event parameter
 174  * can be used to retrieve rotary device specific parameters, such as direction, as shown in the sample code.
 175  *
 176  * @since_tizen @if WEARABLE 3.0 @endif
 177  *
 178  * @privlevel public
 179  *
 180  * @privilege %http://tizen.org/privilege/ime
 181  *
 182  * @param[in] event_handle The input device event handle
 183  * @param[out] direction The direction that the rotary input device was rotated to
 184  *
 185  * @return 0 on success, otherwise a negative error value
 186  * @retval #IME_ERROR_NONE No error
 187  * @retval #IME_ERROR_PERMISSION_DENIED The application does not have the privilege to call this function
 188  * @retval #IME_ERROR_INVALID_PARAMETER Invalid parameter
 189  * @retval #IME_ERROR_NOT_RUNNING IME main loop isn't started yet
 190  *
 191  * @see ime_input_device_rotary_direction_e
 192  * @see ime_process_input_device_event_cb()
 193  *
 194  * @code
 195  static void inputmethod_process_input_device_event_cb(ime_input_device_type_e device_type, ime_input_device_event_h device_event)
 196  {
 197     if (device_type == IME_INPUT_DEVICE_TYPE_ROTARY) {
 198         ime_input_device_rotary_direction_e direction;
 199         if (IME_ERROR_NONE == ime_input_device_rotary_get_direction(device_event, &direction)) {
 200             dlog_print(DLOG_INFO, "INPUTMETHOD", "Direction : %d", direction);
 201         }
 202     }
 203  }
 204  * @endcode
 205  */
 206 int ime_input_device_rotary_get_direction(ime_input_device_event_h event_handle, ime_input_device_rotary_direction_e *direction);
 207
 208 #ifdef __cplusplus
 209 }
 210 #endif
 211
 212 /**
 213  * @}
 214  */
 215
 216 #endif /* __TIZEN_UIX_INPUTMETHOD_DEVICE_EVENT_H__ */