efl-util.h added detail comments and fix TYPO
[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  * @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 Permission denied
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  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
135  * @remarks An application can check error by the return value of efl_util_set_notification_window_level.
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  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
153  * @remarks An application can check error by the return value of efl_util_set_notification_window_level.
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 Permission denied
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  * @since_tizen 2.4
226  * @remarks An application can check error by the return value of efl_util_set_window_screen_mode.
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  * @since_tizen 2.4
244  * @remarks An application can check error by the return value of efl_util_set_window_screen_mode.
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 described 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__ */