2 * Copyright (c) 2015 - 2016 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.
18 #ifndef __TIZEN_APPFW_WIDGET_APP_H__
19 #define __TIZEN_APPFW_WIDGET_APP_H__
22 #include <app_control.h>
23 #include <app_common.h>
25 #include <widget_errno.h>
32 * @addtogroup CAPI_WIDGET_APP_MODULE
37 * @brief Destroy type of widget instance.
40 typedef enum widget_app_destroy_type {
41 WIDGET_APP_DESTROY_TYPE_DEFAULT = 0x00, /**< Deleted */
42 WIDGET_APP_DESTROY_TYPE_UPGRADE = 0x01, /**< Deleted for upgrading */
43 WIDGET_APP_DESTROY_TYPE_UNINSTALL = 0x02, /**< Deleted by uninstalling */
44 WIDGET_APP_DESTROY_TYPE_TERMINATE = 0x03, /**< Deleted for reboot device */
45 WIDGET_APP_DESTROY_TYPE_FAULT = 0x04, /**< Deleted by system-fault */
46 WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x05, /**< Temporarly deleted, will be created again */
47 WIDGET_APP_DESTROY_TYPE_UNKNOWN = 0x06 /**< Undefined reason */
48 } widget_app_destroy_type_e; /**< Delete type */
51 * @brief The handle for widget class.
54 typedef struct _widget_class *widget_class_h;
57 * @brief The handle for widget context.
60 typedef struct _widget_context *widget_context_h;
63 * @brief Called when the widget instance starts.
66 * @details The callback function is called after widget instance is created.
67 * In this callback, you can initialize resources for this instance.
69 * @param[in] context The context of widget instance.
70 * @param[in] content The data set for the previous status
71 * @param[in] w The pixel value for widget width
72 * @param[in] h The pixel value for widget height
73 * @param[in] user_data The user data passed from widget_app_class_create function
75 * @return #WIDGET_ERROR_NONE on success,
76 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
78 typedef int (*widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data);
81 * @brief Called before the widget instance is destroyed.
84 * @details The callback function is called before widget instance is destroyed.
85 * In this callback, you can finalize resources for this instance.
86 * If reason is not #WIDGET_APP_DESTROY_TYPE_DEFAULT, It should store the current status by using incoming bundle.
88 * @param[in] context The context of widget instance.
89 * @param[in] reason The reason for destruction
90 * @param[in,out] content The data set to save
91 * @param[in] user_data The user data passed from widget_app_class_create function
92 * @remark Note that the parameter 'content' is used to save the status of the widget instance.
93 * As a input parameter, content contains the saved status of the widget instance.
94 * You can fill the content parameter with the current status in this callback,
95 * then the framework will save the content by receiving it as a output parameter.
96 * Consequently, you should not use widget_app_context_set_content_info() api in this callback.
97 * The content will be overwritten after this callback returns with the 'content' parameter.
99 * @return #WIDGET_ERROR_NONE on success,
100 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
102 typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data);
105 * @brief Called when the widget is invisible.
108 * @details The callback function is called when the widget is invisible.
109 * The paused instance may be destroyed by framework.
111 * @param[in] context The context of widget instance
112 * @param[in] user_data The user data passed from widget_app_class_create function
113 * @return #WIDGET_ERROR_NONE on success,
114 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
116 typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_data);
119 * @brief Called when the widget is visible.
122 * @details The callback function is called when the widget is visible.
124 * @param[in] context The context of widget instance
125 * @param[in] user_data The user data passed from widget_app_class_create function
126 * @return #WIDGET_ERROR_NONE on success,
127 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
129 typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_data);
132 * @brief Called before the widget size is changed.
135 * @details The callback function is called before the widget size is changed.
137 * @param[in] context The context of widget instance
138 * @param[in] w The pixel value for widget width
139 * @param[in] h The pixel value for widget height
140 * @param[in] user_data The user data passed from widget_app_class_create function
141 * @return #WIDGET_ERROR_NONE on success,
142 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
144 typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data);
147 * @brief Called when the event for updating widget is received.
150 * @details The callback function is called when the event for updating widget is received.
152 * @param[in] context The context of widget instance.
153 * @param[in] content The data set for updating this widget. It will be provided by requester.
154 * Requester can use widget_service_trigger_update()
155 * @param[in] force Although the widget is paused, if it is TRUE, the widget can be updated
156 * @param[in] user_data The user data passed from widget_app_class_create function
157 * @return #WIDGET_ERROR_NONE on success,
158 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
159 * @see widget_service_trigger_update()
161 typedef int (*widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data);
164 * @brief The structure for lifecycle of a widget instance.
168 widget_instance_create_cb create; /**< The callback function is called after widget instance is created. */
169 widget_instance_destroy_cb destroy; /**< The callback function is called before widget instance is destroyed. */
170 widget_instance_pause_cb pause; /**< The callback function is called when the widget is invisible. */
171 widget_instance_resume_cb resume; /**< The callback function is called when the widget is visible. */
172 widget_instance_resize_cb resize; /**< The callback function is called before the widget size is changed. */
173 widget_instance_update_cb update; /**< The callback function is called when the event for updating widget is received. */
174 } widget_instance_lifecycle_callback_s;
177 * @brief Called when the application starts.
180 * @details The callback function is called before the main loop of the application starts.
181 * In this callback, you can initialize resources which can be shared among widget instances.
182 * This function should return the handle for widget class so that it will be used for making instances of widget.
184 * @param[in] user_data The user data passed from the callback registration function
185 * @return The object of widget class
186 * @see widget_app_main()
189 * static widget_class_h __widget_app_created(void *user_data)
191 * widget_instance_lifecycle_callback_s callback = { .... };
193 * return widget_app_class_create(callback);
198 typedef widget_class_h (*widget_app_create_cb)(void *user_data);
201 * @brief Called when the application's main loop exits.
202 * @details This callback function is called once after the main loop of the application exits.
203 * You should release the application's resources in this function.
206 * @param[in] user_data The user data passed from the callback registration function
207 * @see widget_app_main()
209 typedef void (*widget_app_terminate_cb)(void *user_data);
212 * @brief The structure for lifecycle of a widget application.
216 widget_app_create_cb create; /**< The callback function is called before the main loop of the application starts. */
217 widget_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
218 } widget_app_lifecycle_callback_s;
221 * @brief Called for each widget context.
224 * @details This function will be called in the function of widget_app_foreach_context repeatedly.
226 * @param[in] context The context for widget instance
227 * @param[in] data The data for caller
228 * @return true to continue with the next iteration of the loop,
229 * otherwise false to break out of the loop.
230 * @see widget_app_foreach_context()
232 typedef bool (*widget_context_cb)(widget_context_h context, void *data);
235 * @brief Runs the main loop of the application until widget_app_exit() is called.
238 * @param[in] argc The argument count
239 * @param[in] argv The argument vector
240 * @param[in] callback The set of callback functions to handle application events
241 * @param[in] user_data The user data to be passed to the callback functions
243 * @return #WIDGET_ERROR_NONE on success,
244 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
245 * @retval #WIDGET_ERROR_NONE Successful
246 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
247 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
248 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
249 * @see widget_app_exit()
251 int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data);
254 * @brief Exits the main loop of the application.
255 * @details The main loop of the application stops and widget_app_terminate_cb() is invoked.
258 * @return #WIDGET_ERROR_NONE on success,
259 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
260 * @retval #WIDGET_ERROR_NONE Successful
261 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
262 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
263 * @see widget_app_main()
264 * @see widget_app_terminate_cb()
266 int widget_app_exit(void);
269 * @brief Finishes context for the widget instance.
272 * @param[in] context The context for widget instance
274 * @return #WIDGET_ERROR_NONE on success,
275 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
276 * @retval #WIDGET_ERROR_NONE Successful
277 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
278 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
279 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
281 int widget_app_terminate_context(widget_context_h context);
284 * @brief Retrieves all widget contexts in this application.
287 * @param[in] callback The iteration callback function
288 * @param[in] data The data for the callback function
290 * @return #WIDGET_ERROR_NONE on success,
291 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
292 * @retval #WIDGET_ERROR_NONE Successful
293 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
294 * @retval #WIDGET_ERROR_CANCELED The iteration is canceled
295 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
296 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
297 * @see widget_app_foreach_context()
299 int widget_app_foreach_context(widget_context_cb callback, void *data);
302 * @brief Adds the system event handler.
305 * @param[out] event_handler The event handler
306 * @param[in] event_type The system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported
307 * @param[in] callback The callback function
308 * @param[in] user_data The user data to be passed to the callback function
310 * @return #WIDGET_ERROR_NONE on success,
311 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
312 * @retval #WIDGET_ERROR_NONE Successful
313 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
314 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
315 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
316 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
317 * @see app_event_type_e
318 * @see app_event_cb()
319 * @see watch_app_remove_event_handler()
321 int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type,
322 app_event_cb callback, void *user_data);
325 * @brief Removes registered event handler.
328 * @param[in] event_handler The event handler
330 * @return #WIDGET_ERROR_NONE on success,
331 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
332 * @retval #WIDGET_ERROR_NONE Successful
333 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
334 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
335 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
336 * @see watch_app_add_event_handler()
338 int widget_app_remove_event_handler(app_event_handler_h event_handler);
341 * @brief Gets a widget instance id.
344 * @param[in] context The context for widget instance
346 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
347 * @return Widget ID on success, otherwise NULL
348 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
349 * @exception #WIDGET_ERROR_FAULT Unrecoverable error
350 * @remark You must not free returned Widget ID
351 * @see get_last_result()
353 const char *widget_app_get_id(widget_context_h context);
356 * @brief Makes a class for widget instances.
359 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
360 * @param[in] callback The set of lifecycle callbacks
361 * @param[in] user_data The user data to be passed to the callback functions
362 * @return The new widget class object. NULL on error
363 * @exception #WIDGET_ERROR_NONE Successfully added
364 * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
365 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
366 * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
367 * @see get_last_result()
369 widget_class_h widget_app_class_create(widget_instance_lifecycle_callback_s callback, void *user_data);
372 * @brief Sets a tag in the context.
375 * @param[in] context The context for widget instance
376 * @param[in] tag The value to save
378 * @return #WIDGET_ERROR_NONE on success,
379 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
380 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
381 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
382 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
384 int widget_app_context_set_tag(widget_context_h context, void *tag);
387 * @brief Gets the tag in the context.
390 * @param[in] context The context for widget instance
391 * @param[out] tag The value to get
392 * @return #WIDGET_ERROR_NONE on success,
393 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
394 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
395 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
396 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
398 int widget_app_context_get_tag(widget_context_h context, void **tag);
401 * @brief Sets the content info to the widget.
403 * @param[in] context The context for widget instance
404 * @param[in] content_info The data set to save
405 * @return #WIDGET_ERROR_NONE on success,
406 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
407 * @retval #WIDGET_ERROR_NONE Successfully sent
408 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
409 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
410 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
411 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
413 int widget_app_context_set_content_info(widget_context_h context, bundle *content_info);
416 * @brief Sends the title to the widget.
418 * @param[in] context The context for widget instance
419 * @param[in] title When an accessibility mode is turned on, this string will be read
420 * @return #WIDGET_ERROR_NONE on success,
421 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
422 * @retval #WIDGET_ERROR_NONE Successfully sent
423 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
424 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
425 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
426 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
428 int widget_app_context_set_title(widget_context_h context, const char *title);
431 * @brief Adds an additional widget class for multi-class of widget instantiation.
433 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
434 * @param[in] widget_class The result of widget_app_class_create()
435 * @param[in] class_id The class id of provider
436 * @param[in] callback The set of lifecycle callbacks
437 * @param[in] user_data The user data to be passed to the callback functions
438 * @return The new widget class object. NULL on error
439 * @exception #WIDGET_ERROR_NONE Successfully added
440 * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
441 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
442 * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
443 * @see get_last_result()
445 widget_class_h widget_app_class_add(widget_class_h widget_class, const char *class_id,
446 widget_instance_lifecycle_callback_s callback, void *user_data);
456 #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */