include/efl_util.h

   1 /*
   2  * Copyright (c) 2011-2015 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_UI_EFL_UTIL_H__
  18 #define __TIZEN_UI_EFL_UTIL_H__
  19
  20 #include <tizen.h>
  21 #include <Evas.h>
  22 #include <tbm_surface.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 #ifdef __GNUC__
  29 # if __GNUC__ >= 4
  30 #  ifndef API
  31 #   define API __attribute__ ((visibility("default")))
  32 #  endif
  33 # endif
  34 #endif
  35
  36 /**
  37  * @file efl_util.h
  38  */
  39
  40 /**
  41  * @addtogroup CAPI_EFL_UTIL_MODULE
  42  * @{
  43  */
  44
  45 /**
  46  * @brief Enumeration for EFL UTIL ERROR.
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  */
  49 typedef enum
  50 {
  51    EFL_UTIL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
  52    EFL_UTIL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  53    EFL_UTIL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
  54    EFL_UTIL_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permisson denied */
  55    EFL_UTIL_ERROR_NO_SUCH_DEVICE = TIZEN_ERROR_NO_SUCH_DEVICE, /**< @platform No such device or address (@b Since: 2.4) */
  56    EFL_UTIL_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< @platform Function not implemented (@b Since: 2.4) */
  57    EFL_UTIL_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< @platform Not supported (@b Since: 2.4) */
  58    EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE = TIZEN_ERROR_EFL_UTIL | 0x01, /**< Window type not supported */
  59    EFL_UTIL_ERROR_SCREENSHOT_INIT_FAIL = TIZEN_ERROR_EFL_UTIL | 0x02,  /**< @platform Screenshot initialization fail (@b Since: 2.4) */
  60    EFL_UTIL_ERROR_SCREENSHOT_EXECUTION_FAIL = TIZEN_ERROR_EFL_UTIL | 0x03  /**< @platform Screenshot execution fail (@b Since: 2.4) */
  61 } efl_util_error_e;
  62
  63 /**
  64  * @brief Enumeration of notification window's priority level.
  65  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  66  */
  67 typedef enum
  68 {
  69    EFL_UTIL_NOTIFICATION_LEVEL_1, /**< Default notification level. (Deprecated since 2.4. Use EFL_UTIL_NOTIFICATION_LEVEL_DEFAULT instead.) */
  70    EFL_UTIL_NOTIFICATION_LEVEL_2, /**< Higher notification level than default. (Deprecated since 2.4. Use EFL_UTIL_NOTIFICATION_LEVEL_MEDIUM instead.) */
  71    EFL_UTIL_NOTIFICATION_LEVEL_3, /**< The highest notification level. (Deprecated since 2.4. Use EFL_UTIL_NOTIFICATION_LEVEL_TOP instead.) */
  72    EFL_UTIL_NOTIFICATION_LEVEL_NONE    = -1, /**< No (reset) notification level. This value makes the window place in normal layer. (@b Since: 2.4) */
  73    EFL_UTIL_NOTIFICATION_LEVEL_DEFAULT = 10, /**< Default notification level. (@b Since: 2.4) */
  74    EFL_UTIL_NOTIFICATION_LEVEL_MEDIUM  = 20, /**< Higher notification level than default. (@b Since: 2.4) */
  75    EFL_UTIL_NOTIFICATION_LEVEL_HIGH    = 30, /**< Higher notification level than medium. (@b Since: 2.4) */
  76    EFL_UTIL_NOTIFICATION_LEVEL_TOP     = 40  /**< The highest notification level. (@b Since: 2.4) */
  77 } efl_util_notification_level_e;
  78
  79 /**
  80  * @brief Enumeration of screen mode.
  81  * @since_tizen 2.4
  82  */
  83 typedef enum
  84 {
  85    EFL_UTIL_SCREEN_MODE_DEFAULT, /**< The mode which turns the screen off after a timeout. */
  86    EFL_UTIL_SCREEN_MODE_ALWAYS_ON, /**< The mode which keeps the screen turned on. */
  87 } efl_util_screen_mode_e;
  88
  89 /**
  90  * @brief Sets the priority level for the specified notification window.
  91  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  92  * @privlevel public
  93  * @privilege %http://tizen.org/privilege/window.priority.set
  94  * @remarks This API can be used for a notification type window only.
  95  * @param[in] window The EFL window
  96  * @param[in] level The notification window level
  97  * @return @c 0 on success, otherwise a negative error value
  98  * @retval #EFL_UTIL_ERROR_NONE Successful
  99  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 100  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 101  * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Unprevilige access
 102  */
 103 API int efl_util_set_notification_window_level(Evas_Object *window, efl_util_notification_level_e level);
 104
 105 /**
 106  * @brief Gets the priority level for the specified notification window.
 107  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 108  *
 109  * @remarks This API can be used for a notification type window only.
 110  * @param[in] window The EFL window
 111  * @param[out] level The notification window level
 112  * @return @c 0 on success, otherwise a negative error value
 113  * @retval #EFL_UTIL_ERROR_NONE Successful
 114  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 115  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
 116  */
 117 API int efl_util_get_notification_window_level(Evas_Object *window, efl_util_notification_level_e *level);
 118
 119 /**
 120  * @deprecated Deprecated since_tizen 3.0
 121  * @brief Called when an error occurs for setting notification window level
 122  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 123  * @param[in] window The EFL window
 124  * @param[in] error_code The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
 125  * @param[in] user_data The user data passed from the callback registration function
 126  * @see efl_util_set_notification_window_level_error_cb()
 127  * @see efl_util_unset_notification_window_level_error_cb()
 128  */
 129 typedef void (*efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data);
 130
 131 /**
 132  * @deprecated Deprecated since_tizen 3.0
 133  * @brief Registers a callback function to be invoked when an error which set the notification level occurs.
 134  * @details An application can check error by the return value of efl_util_set_notification_window_level.
 135  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 136  * @param[in] window The EFL window
 137  * @param[in] callback The callback function to register
 138  * @param[in] user_data The user data to be passed to the callback function
 139  * @return @c 0 on success, otherwise a negative error value
 140  * @retval #EFL_UTIL_ERROR_NONE Successful
 141  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 142  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 143  * @post efl_util_notification_window_level_error_cb() will be invoked.
 144  * @see efl_util_unset_notification_window_level_error_cb()
 145  * @see efl_util_notification_window_level_error_cb()
 146  */
 147 API int efl_util_set_notification_window_level_error_cb(Evas_Object *window, efl_util_notification_window_level_error_cb callback, void *user_data);
 148
 149 /**
 150  * @deprecated Deprecated since_tizen 3.0
 151  * @brief Unregisters the callback function.
 152  * @details An application can check error by the return value of efl_util_set_notification_window_level.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 154  * @param[in] window The EFL window
 155  * @return @c 0 on success, otherwise a negative error value
 156  * @retval #EFL_UTIL_ERROR_NONE Successful
 157  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @see efl_util_set_notification_window_level_error_cb()
 159  */
 160 API int efl_util_unset_notification_window_level_error_cb(Evas_Object *window);
 161
 162 /**
 163  * @brief Sets the alpha window's visual state to opaque state
 164  * @details This API sets the alpha window's visual state to opaque state.
 165  *          If the alpha window sets the visual state to the opaque,
 166  *          then the window manager could handle it as the opaque window while calculating visibility.
 167  *          This API will have no effect when used by a non-alpha window.
 168  * @since_tizen 2.4
 169  * @param[in] window The EFL window
 170  * @param[in] opaque The value that indicates whether the window has set a visual state to opaque (0: unset, 1: set)
 171  * @return @c 0 on success, otherwise a negative error value
 172  * @retval #EFL_UTIL_ERROR_NONE Successful
 173  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 174  */
 175 API int efl_util_set_window_opaque_state(Evas_Object *window, int opaque);
 176
 177 /**
 178  * @brief Sets the window's screen mode.
 179  * @details This API is useful when the application need to keep the display turned on.
 180  *          If the application set the mode to #EFL_UTIL_SCREEN_MODE_ALWAYS_ON to its window and the window is shown wholly or partially,
 181  *          the window manager requests the display system to keep the display on as long as the window is shown.
 182  *          If the window is no longer shown, then the window manger request the display system to go back to normal operation.
 183  *          Default screen mode of window is #EFL_UTIL_SCREEN_MODE_DEFAULT.
 184  * @since_tizen 2.4
 185  * @privlevel public
 186  * @privilege %http://tizen.org/privilege/display
 187  * @remarks This API needs the privilege.
 188  *          If the application which is not get the privilege use this API, the window manager generates the permission deny error.
 189  *          The application can notice this error if it set the callback function using the efl_util_set_window_screen_mode_error_cb().
 190  * @param[in] window The EFL window
 191  * @param[in] mode The screen mode
 192  * @return @c 0 on success, otherwise a negative error value
 193  * @retval #EFL_UTIL_ERROR_NONE Successful
 194  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Unprevilige access
 196  */
 197 API int efl_util_set_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e mode);
 198
 199 /**
 200  * @brief Gets the screen mode of the specified window.
 201  * @since_tizen 2.4
 202  * @param[in] window The EFL window
 203  * @param[out] mode The screen mode
 204  * @return @c 0 on success, otherwise a negative error value
 205  * @retval #EFL_UTIL_ERROR_NONE Successful
 206  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 207  */
 208 API int efl_util_get_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e *mode);
 209
 210 /**
 211  * @deprecated Deprecated since_tizen 3.0
 212  * @brief Called when an error occurs for setting window's screen mode
 213  * @since_tizen 2.4
 214  * @param[in] window The EFL window
 215  * @param[in] error_code The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
 216  * @param[in] user_data The user data passed from the callback registration function
 217  * @see efl_util_set_window_screen_mode_error_cb()
 218  * @see efl_util_unset_window_screen_mode_error_cb()
 219  */
 220 typedef void (*efl_util_window_screen_mode_error_cb)(Evas_Object *window, int error_code, void *user_data);
 221
 222 /**
 223  * @deprecated Deprecated since_tizen 3.0
 224  * @brief Registers a callback function to be invoked when an error which set the screen mode.
 225  * @details An application can check error by the return value of efl_util_set_window_screen_mode.
 226  * @since_tizen 2.4
 227  * @param[in] window The EFL window
 228  * @param[in] callback The callback function to register
 229  * @param[in] user_data The user data to be passed to the callback function
 230  * @return @c 0 on success, otherwise a negative error value
 231  * @retval #EFL_UTIL_ERROR_NONE Successful
 232  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 233  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
 234  * @post  efl_util_window_screen_mode_error_cb() will be invoked.
 235  * @see efl_util_unset_window_screen_mode_error_cb()
 236  * @see efl_util_window_screen_mode_error_cb()
 237  */
 238 API int efl_util_set_window_screen_mode_error_cb(Evas_Object *window, efl_util_window_screen_mode_error_cb callback, void *user_data);
 239
 240 /**
 241  * @deprecated Deprecated since_tizen 3.0
 242  * @brief Unregisters the callback function.
 243  * @details An application can check error by the return value of efl_util_set_window_screen_mode.
 244  * @since_tizen 2.4
 245  * @param[in] window The EFL window
 246  * @return @c 0 on success, otherwise a negative error value
 247  * @retval #EFL_UTIL_ERROR_NONE Successful
 248  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 249  * @see efl_util_set_window_screen_mode_error_cb()
 250  */
 251 API int efl_util_unset_window_screen_mode_error_cb(Evas_Object *window);
 252
 253 /**
 254  * @}
 255  */
 256
 257 /**
 258  * @addtogroup CAPI_EFL_UTIL_INPUT_MODULE
 259  * @{
 260  */
 261
 262 /**
 263  * @platform
 264  * @brief Enumeration of device type generated events.
 265  * @since_tizen 2.4
 266  */
 267 typedef enum
 268 {
 269    EFL_UTIL_INPUT_DEVTYPE_NONE,
 270    EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN, /**< Touch Screen device */
 271    EFL_UTIL_INPUT_DEVTYPE_KEYBOARD, /**< Keyboard device */
 272    EFL_UTIL_INPUT_DEVTYPE_ALL, /**< Both of touch screen and keyboard device */
 273    EFL_UTIL_INPUT_DEVTYPE_MAX
 274 } efl_util_input_device_type_e;
 275
 276 /**
 277  * @platform
 278  * @brief Enumeration of touch event types.
 279  * @since_tizen 2.4
 280  */
 281 typedef enum
 282 {
 283    EFL_UTIL_INPUT_TOUCH_NONE,
 284    EFL_UTIL_INPUT_TOUCH_BEGIN, /**< Finger press. It is same a behavior put your finger on touch screen */
 285    EFL_UTIL_INPUT_TOUCH_UPDATE, /**< Finger move. It is same a behavior move your finger on touch screen */
 286    EFL_UTIL_INPUT_TOUCH_END, /**< Finger release. It is same a behavior release your finger on touch screen */
 287    EFL_UTIL_INPUT_TOUCH_MAX
 288 } efl_util_input_touch_type_e;
 289
 290 /**
 291  * @platform
 292  * @brief Initializes system and check input generate functions are supported, open devices generated events.
 293  * @since_tizen 2.4
 294  * @privlevel platform
 295  * @privilege %http://tizen.org/privilege/inputgenerator
 296  * @param[in] dev_type The device type want to generate events (ex> EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN, EFL_UTIL_INPUT_DEVTYPE_KEYBOARD, EFL_UTIL_INPUT_DEVTYPE_ALL)
 297  * @return @c 0 on success, otherwise a negative error value
 298  * @retval #EFL_UTIL_ERROR_NONE Successful
 299  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 300  * @retval #EFL_UTIL_ERROR_NO_SUCH_DEVICE No such device or address
 301  * @retval #EFL_UTIL_ERROR_INVALID_OPERATION Function not implemented
 302  * @see efl_util_input_generate_deinit()
 303  */
 304 API int efl_util_input_initialize_generator(efl_util_input_device_type_e dev_type);
 305
 306 /**
 307  * @platform
 308  * @brief Deinitializes system and close opened devices.
 309  * @since_tizen 2.4
 310  * @privlevel platform
 311  * @privilege %http://tizen.org/privilege/inputgenerator
 312  * @see efl_util_input_generate_init()
 313  */
 314 API void efl_util_input_deinitialize_generator(void);
 315
 316 /**
 317  * @platform
 318  * @brief Generates all of key events using a opened device.
 319  * @since_tizen 2.4
 320  * @privlevel platform
 321  * @privilege %http://tizen.org/privilege/inputgenerator
 322  * @param[in] key_name The key name want to generate
 323  * @param[in] pressed The value that select key press or release (0: release, 1: press)
 324  * @return @c 0 on success, otherwise a negative error value
 325  * @retval #EFL_UTIL_ERROR_NONE Successful
 326  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 327  */
 328 API int efl_util_input_generate_key(const char *key_name, int pressed);
 329
 330 /**
 331  * @platform
 332  * @brief Generates a touch event using a opened device.
 333  * @since_tizen 2.4
 334  * @privlevel platform
 335  * @privilege %http://tizen.org/privilege/inputgenerator
 336  * @param[in] idx The index of touched finger
 337  * @param[in] efl_util_input_touch_type_e The touch type (ex> EFL_UTIL_INPUT_TOUCH_BEGIN, EFL_UTIL_INPUT_TOUCH_UPDATE, EFL_UTIL_INPUT_TOUCH_END)
 338  * @return @c 0 on success, otherwise a negative error value
 339  * @retval #EFL_UTIL_ERROR_NONE Successful
 340  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 341  */
 342 API int efl_util_input_generate_touch(int idx, efl_util_input_touch_type_e touch_type, int x, int y);
 343
 344 /**
 345  * @}
 346  */
 347
 348 /**
 349  * @addtogroup CAPI_EFL_UTIL_SCREENSHOT_MODULE
 350  * @{
 351  */
 352
 353 /**
 354  * @platform
 355  * @brief Definition for the screenshot handle.
 356  * @since_tizen 2.4
 357  */
 358 typedef struct _efl_util_screenshot_h * efl_util_screenshot_h;
 359
 360 /**
 361  * @platform
 362  * @brief Initializes the screenshot.
 363  * @since_tizen 2.4
 364  * @privlevel platform
 365  * @privilege %http://tizen.org/privilege/screenshot
 366  * @remarks The specific error code can be obtained using the get_last_result()
 367  * method. Error codes are dedescribed in Exception section.
 368  * @param[in] width width of the screenshot surface
 369  * @param[in] height height of the screenshot surface
 370  * @return #efl_util_screenshot_h on success, otherwise @c NULL
 371  * @retval #efl_util_screenshot_h  The screenshot handle
 372  * @exception #EFL_UTIL_ERROR_NONE Successful
 373  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 374  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
 375  * @exception #EFL_UTIL_ERROR_SCREENSHOT_INIT_FAIL Initialization failure
 376  * @see efl_util_screenshot_deinitialize()
 377  */
 378 API efl_util_screenshot_h efl_util_screenshot_initialize(int width, int height);
 379
 380 /**
 381  * @platform
 382  * @brief Takes a screenshot and get a tbm_surface handle.
 383  * @since_tizen 2.4
 384  * @privlevel platform
 385  * @privilege %http://tizen.org/privilege/screenshot
 386  * @remarks The specific error code can be obtained using the get_last_result()
 387  *          The tbm_surface_h must be free by caller
 388  * @param[in] screenshot efl_util_screenshot_h handle
 389  * @return #tbm_surface_h on success, otherwise @c NULL
 390  * @retval #tbm_surface_h The TBM surface handle
 391  * @exception #EFL_UTIL_ERROR_NONE Successful
 392  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 393  * @exception #EFL_UTIL_ERROR_SCREENSHOT_EXECUTION_FAIL Execution failure
 394  * @see efl_util_screenshot_initialize()
 395  * @see efl_util_screenshot_deinitialize()
 396  */
 397 API tbm_surface_h efl_util_screenshot_take_tbm_surface(efl_util_screenshot_h screenshot);
 398
 399 /**
 400  * @platform
 401  * @brief Deinitializes the screenshot.
 402  * @since_tizen 2.4
 403  * @privlevel platform
 404  * @privilege %http://tizen.org/privilege/screenshot
 405  * @param[in]  screenshot  efl_util_screenshot_h handle
 406  * @return @c 0 on success, otherwise a negative error value
 407  * @retval #EFL_UTIL_ERROR_NONE Successful
 408  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
 409  * @see efl_util_screenshot_initialize()
 410  */
 411 API int efl_util_screenshot_deinitialize(efl_util_screenshot_h screenshot);
 412
 413 /**
 414  * @}
 415  */
 416
 417 #ifdef __cplusplus
 418 }
 419 #endif
 420 #endif /* __TIZEN_UI_EFL_UTIL_H__ */