2 * Copyright (c) 2011-2015 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_UI_EFL_UTIL_H__
18 #define __TIZEN_UI_EFL_UTIL_H__
22 #include <tbm_surface.h>
31 # define API __attribute__ ((visibility("default")))
41 * @addtogroup CAPI_EFL_UTIL_MODULE
46 * @brief Enumeration for EFL UTIL ERROR.
47 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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) */
64 * @brief Enumeration of notification window's priority level.
65 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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;
80 * @brief Enumeration of screen mode.
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;
90 * @brief Sets the priority level for the specified notification window.
91 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
103 API int efl_util_set_notification_window_level(Evas_Object *window, efl_util_notification_level_e level);
106 * @brief Gets the priority level for the specified notification window.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
117 API int efl_util_get_notification_window_level(Evas_Object *window, efl_util_notification_level_e *level);
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()
129 typedef void (*efl_util_notification_window_level_error_cb)(Evas_Object *window, int error_code, void *user_data);
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()
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);
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()
160 API int efl_util_unset_notification_window_level_error_cb(Evas_Object *window);
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.
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
175 API int efl_util_set_window_opaque_state(Evas_Object *window, int opaque);
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.
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
197 API int efl_util_set_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e mode);
200 * @brief Gets the screen mode of the specified window.
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
208 API int efl_util_get_window_screen_mode(Evas_Object *window, efl_util_screen_mode_e *mode);
211 * @deprecated Deprecated since_tizen 3.0.
212 * @brief Called when an error occurs for setting window's screen mode
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()
220 typedef void (*efl_util_window_screen_mode_error_cb)(Evas_Object *window, int error_code, void *user_data);
223 * @deprecated Deprecated since_tizen 3.0.
224 * @brief Registers a callback function to be invoked when an error which set the screen mode.
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()
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);
241 * @deprecated Deprecated since_tizen 3.0.
242 * @brief Unregisters the callback function.
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()
251 API int efl_util_unset_window_screen_mode_error_cb(Evas_Object *window);
258 * @addtogroup CAPI_EFL_UTIL_INPUT_MODULE
264 * @brief Enumeration of device type generated events.
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;
278 * @brief Enumeration of touch event types.
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;
292 * @brief Initializes system and check input generate functions are supported, open devices generated events.
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()
304 API int efl_util_input_initialize_generator(efl_util_input_device_type_e dev_type);
308 * @brief Deinitializes system and close opened devices.
310 * @privlevel platform
311 * @privilege %http://tizen.org/privilege/inputgenerator
312 * @see efl_util_input_generate_init()
314 API void efl_util_input_deinitialize_generator(void);
318 * @brief Generates all of key events using a opened device.
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
328 API int efl_util_input_generate_key(const char *key_name, int pressed);
332 * @brief Generates a touch event using a opened device.
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
342 API int efl_util_input_generate_touch(int idx, efl_util_input_touch_type_e touch_type, int x, int y);
349 * @addtogroup CAPI_EFL_UTIL_SCREENSHOT_MODULE
355 * @brief Definition for the screenshot handle.
358 typedef struct _efl_util_screenshot_h * efl_util_screenshot_h;
362 * @brief Initializes the screenshot.
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()
378 API efl_util_screenshot_h efl_util_screenshot_initialize(int width, int height);
382 * @brief Takes a screenshot and get a tbm_surface handle.
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()
397 API tbm_surface_h efl_util_screenshot_take_tbm_surface(efl_util_screenshot_h screenshot);
401 * @brief Deinitializes the screenshot.
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()
411 API int efl_util_screenshot_deinitialize(efl_util_screenshot_h screenshot);
420 #endif /* __TIZEN_UI_EFL_UTIL_H__ */