7ee6fcaefe0eddd8245bb95d68a45e8d06bca545
[platform/core/api/efl-util.git] / 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, /**< Permission 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  *          Up to the version 2.4, it supports as async APIs.
96  *          But it is synchronous call since Tizen 3.0
97  * @param[in] window The EFL window
98  * @param[in] level The notification window level
99  * @return @c 0 on success, otherwise a negative error value
100  * @retval #EFL_UTIL_ERROR_NONE Successful
101  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
102  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
103  * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Permission denied
104  */
105 API int efl_util_set_notification_window_level(Evas_Object *window, efl_util_notification_level_e level);
106
107 /**
108  * @brief Gets the priority level for the specified notification window.
109  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110  *
111  * @remarks This API can be used for a notification type window only.
112  *          Up to the version 2.4, it supports as async APIs.
113  *          But it is synchronous call since Tizen 3.0
114  * @param[in] window The EFL window
115  * @param[out] level The notification window level
116  * @return @c 0 on success, otherwise a negative error value
117  * @retval #EFL_UTIL_ERROR_NONE Successful
118  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
119  * @retval #EFL_UTIL_ERROR_NOT_SUPPORTED_WINDOW_TYPE Window type not supported
120  */
121 API int efl_util_get_notification_window_level(Evas_Object *window, efl_util_notification_level_e *level);
122
123 /**
124  * @deprecated Deprecated since_tizen 3.0.
125  * @brief Called when an error occurs for setting notification window level
126  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
127  * @remarks An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
128  * @param[in] window The EFL window
129  * @param[in] error_code The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
130  * @param[in] user_data The user data passed from the callback registration function
131  * @see efl_util_set_notification_window_level_error_cb()
132  * @see efl_util_unset_notification_window_level_error_cb()
133  */
134 typedef void (*efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data);
135
136 /**
137  * @deprecated Deprecated since_tizen 3.0.
138  * @brief Registers a callback function to be invoked when an error which set the notification level occurs.
139  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
140  * @remarks An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
141  * @param[in] window The EFL window
142  * @param[in] callback The callback function to register
143  * @param[in] user_data The user data to be passed to the callback function
144  * @return @c 0 on success, otherwise a negative error value
145  * @retval #EFL_UTIL_ERROR_NONE Successful
146  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
147  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
148  * @post efl_util_notification_window_level_error_cb() will be invoked.
149  * @see efl_util_unset_notification_window_level_error_cb()
150  * @see efl_util_notification_window_level_error_cb()
151  */
152 API int efl_util_set_notification_window_level_error_cb(Evas_Object *window, efl_util_notification_window_level_error_cb callback, void *user_data);
153
154 /**
155  * @deprecated Deprecated since_tizen 3.0.
156  * @brief Unregisters the callback function.
157  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
158  * @remarks An application can check error by the return value of efl_util_set_notification_window_level since 3.0.
159  * @param[in] window The EFL window
160  * @return @c 0 on success, otherwise a negative error value
161  * @retval #EFL_UTIL_ERROR_NONE Successful
162  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
163  * @see efl_util_set_notification_window_level_error_cb()
164  */
165 API int efl_util_unset_notification_window_level_error_cb(Evas_Object *window);
166
167 /**
168  * @brief Sets the alpha window's visual state to opaque state
169  * @details This API sets the alpha window's visual state to opaque state.
170  *          If the alpha window sets the visual state to the opaque,
171  *          then the window manager could handle it as the opaque window while calculating visibility.
172  *          This API will have no effect when used by a non-alpha window.
173  * @since_tizen 2.4
174  * @param[in] window The EFL window
175  * @param[in] opaque The value that indicates whether the window has set a visual state to opaque (0: unset, 1: set)
176  * @return @c 0 on success, otherwise a negative error value
177  * @retval #EFL_UTIL_ERROR_NONE Successful
178  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
179  */
180 API int efl_util_set_window_opaque_state(Evas_Object *window, int opaque);
181
182 /**
183  * @brief Sets the window's screen mode.
184  * @details This API is useful when the application need to keep the display turned on.
185  *          If the application set the mode to #EFL_UTIL_SCREEN_MODE_ALWAYS_ON to its window and the window is shown wholly or partially,
186  *          the window manager requests the display system to keep the display on as long as the window is shown.
187  *          If the window is no longer shown, then the window manger request the display system to go back to normal operation.
188  *          Default screen mode of window is #EFL_UTIL_SCREEN_MODE_DEFAULT.
189  * @since_tizen 2.4
190  * @privlevel public
191  * @privilege %http://tizen.org/privilege/display
192  * @remarks This API needs the privilege.
193  *          If the application which is not get the privilege use this API, the window manager generates the permission deny error.
194  *          The application can notice this error if it set the callback function using the efl_util_set_window_screen_mode_error_cb().
195  * @param[in] window The EFL window
196  * @param[in] mode The screen mode
197  * @return @c 0 on success, otherwise a negative error value
198  * @retval #EFL_UTIL_ERROR_NONE Successful
199  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
200  * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Permission denied
201  */
202 API int efl_util_set_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e mode);
203
204 /**
205  * @brief Gets the screen mode of the specified window.
206  * @since_tizen 2.4
207  * @param[in] window The EFL window
208  * @param[out] mode The screen mode
209  * @return @c 0 on success, otherwise a negative error value
210  * @retval #EFL_UTIL_ERROR_NONE Successful
211  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
212  */
213 API int efl_util_get_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e *mode);
214
215 /**
216  * @deprecated Deprecated since_tizen 3.0.
217  * @brief Called when an error occurs for setting window's screen mode
218  * @since_tizen 2.4
219  * @remarks An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
220  * @param[in] window The EFL window
221  * @param[in] error_code The error code (#EFL_UTIL_ERROR_PERMISSION_DENIED)
222  * @param[in] user_data The user data passed from the callback registration function
223  * @see efl_util_set_window_screen_mode_error_cb()
224  * @see efl_util_unset_window_screen_mode_error_cb()
225  */
226 typedef void (*efl_util_window_screen_mode_error_cb)(Evas_Object *window, int error_code, void *user_data);
227
228 /**
229  * @deprecated Deprecated since_tizen 3.0.
230  * @brief Registers a callback function to be invoked when an error which set the screen mode.
231  * @since_tizen 2.4
232  * @remarks An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
233  * @param[in] window The EFL window
234  * @param[in] callback The callback function to register
235  * @param[in] user_data The user data to be passed to the callback function
236  * @return @c 0 on success, otherwise a negative error value
237  * @retval #EFL_UTIL_ERROR_NONE Successful
238  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
239  * @retval #EFL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
240  * @post  efl_util_window_screen_mode_error_cb() will be invoked.
241  * @see efl_util_unset_window_screen_mode_error_cb()
242  * @see efl_util_window_screen_mode_error_cb()
243  */
244 API int efl_util_set_window_screen_mode_error_cb(Evas_Object *window, efl_util_window_screen_mode_error_cb callback, void *user_data);
245
246 /**
247  * @deprecated Deprecated since_tizen 3.0.
248  * @brief Unregisters the callback function.
249  * @since_tizen 2.4
250  * @remarks An application can check error by the return value of efl_util_set_window_screen_mode since 3.0.
251  * @param[in] window The EFL window
252  * @return @c 0 on success, otherwise a negative error value
253  * @retval #EFL_UTIL_ERROR_NONE Successful
254  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
255  * @see efl_util_set_window_screen_mode_error_cb()
256  */
257 API int efl_util_unset_window_screen_mode_error_cb(Evas_Object *window);
258
259 /**
260  * @}
261  */
262
263 /**
264  * @addtogroup CAPI_EFL_UTIL_INPUT_MODULE
265  * @{
266  */
267
268  /**
269   * @platform
270   * @brief Definition for the input generator handle.
271   * @since_tizen 2.4
272   */
273
274  typedef struct _efl_util_inputgen_h * efl_util_inputgen_h;
275
276 /**
277  * @platform
278  * @brief Enumeration of device type generated events.
279  * @since_tizen 2.4
280  */
281 typedef enum
282 {
283    EFL_UTIL_INPUT_DEVTYPE_NONE = 0x0,
284    EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN = (1 << 0), /**< Touch Screen device */
285    EFL_UTIL_INPUT_DEVTYPE_KEYBOARD = (1 << 1), /**< Keyboard device */
286    EFL_UTIL_INPUT_DEVTYPE_ALL = EFL_UTIL_INPUT_DEVTYPE_TOUCHSCREEN |
287                                 EFL_UTIL_INPUT_DEVTYPE_KEYBOARD, /**< Both of touch screen and keyboard device */
288    EFL_UTIL_INPUT_DEVTYPE_MAX = (1 << 10)
289 } efl_util_input_device_type_e;
290
291 /**
292  * @platform
293  * @brief Enumeration of touch event types.
294  * @since_tizen 2.4
295  */
296 typedef enum
297 {
298    EFL_UTIL_INPUT_TOUCH_NONE,
299    EFL_UTIL_INPUT_TOUCH_BEGIN, /**< Finger press. It is same a behavior put your finger on touch screen */
300    EFL_UTIL_INPUT_TOUCH_UPDATE, /**< Finger move. It is same a behavior move your finger on touch screen */
301    EFL_UTIL_INPUT_TOUCH_END, /**< Finger release. It is same a behavior release your finger on touch screen */
302    EFL_UTIL_INPUT_TOUCH_MAX = 10
303 } efl_util_input_touch_type_e;
304
305 /**
306    * @platform
307    * @brief Initializes system and check input generate functions are supported, open devices generated events.
308    * @since_tizen 2.4
309    * @privlevel platform
310    * @privilege %http://tizen.org/privilege/inputgenerator
311    * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
312    * @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)
313    * @return #efl_util_inputgen_h on success, otherwise @c NULL
314    * @retval #efl_util_inputgen_h The input generator handle
315    * @exception #EFL_UTIL_ERROR_NONE Successful
316    * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
317    * @exception #EFL_UTIL_ERROR_NO_SUCH_DEVICE No such device or address
318    * @exception #EFL_UTIL_ERROR_INVALID_OPERATION Function not implemented
319    * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
320    * @see efl_util_input_deinitialize_generator()
321    */
322 API efl_util_inputgen_h efl_util_input_initialize_generator(efl_util_input_device_type_e dev_type);
323
324 /**
325    * @platform
326    * @brief Deinitializes system and close opened devices.
327    * @since_tizen 2.4
328    * @privlevel platform
329    * @privilege %http://tizen.org/privilege/inputgenerator
330    * @param[in] inputgen_h The efl_util_inputgen_h handle
331    * @return @c 0 on success, otherwise a negative error value
332    * @retval #EFL_UTIL_ERROR_NONE Successful
333    * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
334    * @see efl_util_input_initialize_generator()
335    */
336 API int efl_util_input_deinitialize_generator(efl_util_inputgen_h inputgen_h);
337
338 /**
339    * @platform
340    * @brief Generates all of key events using a opened device.
341    * @since_tizen 2.4
342    * @privlevel platform
343    * @privilege %http://tizen.org/privilege/inputgenerator
344    * @param[in] key_name The key name want to generate
345    * @param[in] pressed The value that select key press or release (0: release, 1: press)
346    * @return @c 0 on success, otherwise a negative error value
347    * @retval #EFL_UTIL_ERROR_NONE Successful
348    * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
349    * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Has no permission to generate key
350    */
351 API int efl_util_input_generate_key(efl_util_inputgen_h inputgen_h, const char *key_name, int pressed);
352
353 /**
354    * @platform
355    * @brief Generates a touch event using a opened device.
356    * @since_tizen 2.4
357    * @privlevel platform
358    * @privilege %http://tizen.org/privilege/inputgenerator
359    * @param[in] idx The index of touched finger
360    * @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)
361    * @return @c 0 on success, otherwise a negative error value
362    * @retval #EFL_UTIL_ERROR_NONE Successful
363    * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
364    * @retval #EFL_UTIL_ERROR_PERMISSION_DENIED Has no permission to generate touch
365    */
366 API int efl_util_input_generate_touch(efl_util_inputgen_h inputgen_h, int idx, efl_util_input_touch_type_e touch_type, int x, int y);
367
368 /**
369  * @}
370  */
371
372 /**
373  * @addtogroup CAPI_EFL_UTIL_SCREENSHOT_MODULE
374  * @{
375  */
376
377 /**
378  * @platform
379  * @brief Definition for the screenshot handle.
380  * @since_tizen 2.4
381  */
382 typedef struct _efl_util_screenshot_h * efl_util_screenshot_h;
383
384 /**
385  * @platform
386  * @brief Initializes the screenshot.
387  * @since_tizen 2.4
388  * @privlevel platform
389  * @privilege %http://tizen.org/privilege/screenshot
390  * @remarks The specific error code can be obtained using the get_last_result()
391  * method. Error codes are described in Exception section.
392  * @param[in] width width of the screenshot surface
393  * @param[in] height height of the screenshot surface
394  * @return #efl_util_screenshot_h on success, otherwise @c NULL
395  * @retval #efl_util_screenshot_h  The screenshot handle
396  * @exception #EFL_UTIL_ERROR_NONE Successful
397  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
398  * @exception #EFL_UTIL_ERROR_OUT_OF_MEMORY Memory allocation failure
399  * @exception #EFL_UTIL_ERROR_SCREENSHOT_INIT_FAIL Initialization failure
400  * @see efl_util_screenshot_deinitialize()
401  */
402 API efl_util_screenshot_h efl_util_screenshot_initialize(int width, int height);
403
404 /**
405  * @platform
406  * @brief Takes a screenshot and get a tbm_surface handle.
407  * @since_tizen 2.4
408  * @privlevel platform
409  * @privilege %http://tizen.org/privilege/screenshot
410  * @remarks The specific error code can be obtained using the get_last_result()
411  *          The tbm_surface_h must be free by caller
412  * @param[in] screenshot efl_util_screenshot_h handle
413  * @return #tbm_surface_h on success, otherwise @c NULL
414  * @retval #tbm_surface_h The TBM surface handle
415  * @exception #EFL_UTIL_ERROR_NONE Successful
416  * @exception #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
417  * @exception #EFL_UTIL_ERROR_SCREENSHOT_EXECUTION_FAIL Execution failure
418  * @see efl_util_screenshot_initialize()
419  * @see efl_util_screenshot_deinitialize()
420  */
421 API tbm_surface_h efl_util_screenshot_take_tbm_surface(efl_util_screenshot_h screenshot);
422
423 /**
424  * @platform
425  * @brief Deinitializes the screenshot.
426  * @since_tizen 2.4
427  * @privlevel platform
428  * @privilege %http://tizen.org/privilege/screenshot
429  * @param[in]  screenshot  efl_util_screenshot_h handle
430  * @return @c 0 on success, otherwise a negative error value
431  * @retval #EFL_UTIL_ERROR_NONE Successful
432  * @retval #EFL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
433  * @see efl_util_screenshot_initialize()
434  */
435 API int efl_util_screenshot_deinitialize(efl_util_screenshot_h screenshot);
436
437 /**
438  * @}
439  */
440
441 #ifdef __cplusplus
442 }
443 #endif
444 #endif /* __TIZEN_UI_EFL_UTIL_H__ */