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_PERMANENT = 0x00, /* User deleted this widget from the viewer */
42 WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x01, /* Widget is deleted because of other reasons (e.g. widget process is terminated temporarily by the system) */
43 } widget_app_destroy_type_e; /**< Delete type */
46 * @brief The handle for widget class.
49 typedef struct _widget_class *widget_class_h;
52 * @brief The handle for widget context.
55 typedef struct _widget_context *widget_context_h;
58 * @brief Called when the widget instance starts.
61 * @details The callback function is called after widget instance is created.
62 * In this callback, you can initialize resources for this instance.
64 * @param[in] context The context of widget instance.
65 * @param[in] content The data set for the previous status
66 * @param[in] w The pixel value for widget width
67 * @param[in] h The pixel value for widget height
68 * @param[in] user_data The user data passed from widget_app_class_create function
70 * @return #WIDGET_ERROR_NONE on success,
71 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
73 typedef int (*widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data);
76 * @brief Called before the widget instance is destroyed.
79 * @details The callback function is called before widget instance is destroyed.
80 * In this callback, you can finalize resources for this instance.
81 * If reason is not #WIDGET_APP_DESTROY_TYPE_TEMPORARY, It should store the current status by using incoming bundle.
83 * @param[in] context The context of widget instance.
84 * @param[in] reason The reason for destruction
85 * @param[in,out] content The data set to save
86 * @param[in] user_data The user data passed from widget_app_class_create function
87 * @remark Note that the parameter 'content' is used to save the status of the widget instance.
88 * As a input parameter, content contains the saved status of the widget instance.
89 * You can fill the content parameter with the current status in this callback,
90 * then the framework will save the content by receiving it as a output parameter.
91 * Consequently, you should not use widget_app_context_set_content_info() api in this callback.
92 * The content will be overwritten after this callback returns with the 'content' parameter.
94 * @return #WIDGET_ERROR_NONE on success,
95 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
97 typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data);
100 * @brief Called when the widget is invisible.
103 * @details The callback function is called when the widget is invisible.
104 * The paused instance may be destroyed by framework.
106 * @param[in] context The context of widget instance
107 * @param[in] user_data The user data passed from widget_app_class_create function
108 * @return #WIDGET_ERROR_NONE on success,
109 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
111 typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_data);
114 * @brief Called when the widget is visible.
117 * @details The callback function is called when the widget is visible.
119 * @param[in] context The context of widget instance
120 * @param[in] user_data The user data passed from widget_app_class_create function
121 * @return #WIDGET_ERROR_NONE on success,
122 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
124 typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_data);
127 * @brief Called before the widget size is changed.
130 * @details The callback function is called before the widget size is changed.
132 * @param[in] context The context of widget instance
133 * @param[in] w The pixel value for widget width
134 * @param[in] h The pixel value for widget height
135 * @param[in] user_data The user data passed from widget_app_class_create function
136 * @return #WIDGET_ERROR_NONE on success,
137 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
139 typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data);
142 * @brief Called when the event for updating widget is received.
145 * @details The callback function is called when the event for updating widget is received.
147 * @param[in] context The context of widget instance.
148 * @param[in] content The data set for updating this widget. It will be provided by requester.
149 * Requester can use widget_service_trigger_update()
150 * @param[in] force Although the widget is paused, if it is TRUE, the widget can be updated
151 * @param[in] user_data The user data passed from widget_app_class_create function
152 * @return #WIDGET_ERROR_NONE on success,
153 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
154 * @see widget_service_trigger_update()
156 typedef int (*widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data);
159 * @brief The structure for lifecycle of a widget instance.
163 widget_instance_create_cb create; /**< The callback function is called after widget instance is created. */
164 widget_instance_destroy_cb destroy; /**< The callback function is called before widget instance is destroyed. */
165 widget_instance_pause_cb pause; /**< The callback function is called when the widget is invisible. */
166 widget_instance_resume_cb resume; /**< The callback function is called when the widget is visible. */
167 widget_instance_resize_cb resize; /**< The callback function is called before the widget size is changed. */
168 widget_instance_update_cb update; /**< The callback function is called when the event for updating widget is received. */
169 } widget_instance_lifecycle_callback_s;
172 * @brief Called when the application starts.
175 * @details The callback function is called before the main loop of the application starts.
176 * In this callback, you can initialize resources which can be shared among widget instances.
177 * This function should return the handle for widget class so that it will be used for making instances of widget.
179 * @param[in] user_data The user data passed from the callback registration function
180 * @return The object of widget class
181 * @see widget_app_main()
184 * static widget_class_h __widget_app_created(void *user_data)
186 * widget_instance_lifecycle_callback_s callback = { .... };
188 * return widget_app_class_create(callback);
193 typedef widget_class_h (*widget_app_create_cb)(void *user_data);
196 * @brief Called when the application's main loop exits.
197 * @details This callback function is called once after the main loop of the application exits.
198 * You should release the application's resources in this function.
201 * @param[in] user_data The user data passed from the callback registration function
202 * @see widget_app_main()
204 typedef void (*widget_app_terminate_cb)(void *user_data);
207 * @brief The structure for lifecycle of a widget application.
211 widget_app_create_cb create; /**< The callback function is called before the main loop of the application starts. */
212 widget_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */
213 } widget_app_lifecycle_callback_s;
216 * @brief Called for each widget context.
219 * @details This function will be called in the function of widget_app_foreach_context repeatedly.
221 * @param[in] context The context for widget instance
222 * @param[in] data The data for caller
223 * @return true to continue with the next iteration of the loop,
224 * otherwise false to break out of the loop.
225 * @see widget_app_foreach_context()
227 typedef bool (*widget_context_cb)(widget_context_h context, void *data);
230 * @brief Runs the main loop of the application until widget_app_exit() is called.
233 * @param[in] argc The argument count
234 * @param[in] argv The argument vector
235 * @param[in] callback The set of callback functions to handle application events
236 * @param[in] user_data The user data to be passed to the callback functions
238 * @return #WIDGET_ERROR_NONE on success,
239 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
240 * @retval #WIDGET_ERROR_NONE Successful
241 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
242 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
243 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
244 * @see widget_app_exit()
246 int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data);
249 * @brief Exits the main loop of the application.
250 * @details The main loop of the application stops and widget_app_terminate_cb() is invoked.
253 * @return #WIDGET_ERROR_NONE on success,
254 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
255 * @retval #WIDGET_ERROR_NONE Successful
256 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
257 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
258 * @see widget_app_main()
259 * @see widget_app_terminate_cb()
261 int widget_app_exit(void);
264 * @brief Finishes context for the widget instance.
267 * @param[in] context The context for widget instance
269 * @return #WIDGET_ERROR_NONE on success,
270 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
271 * @retval #WIDGET_ERROR_NONE Successful
272 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
273 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
274 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
276 int widget_app_terminate_context(widget_context_h context);
279 * @brief Retrieves all widget contexts in this application.
282 * @param[in] callback The iteration callback function
283 * @param[in] data The data for the callback function
285 * @return #WIDGET_ERROR_NONE on success,
286 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
287 * @retval #WIDGET_ERROR_NONE Successful
288 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
289 * @retval #WIDGET_ERROR_CANCELED The iteration is canceled
290 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
291 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
292 * @see widget_app_foreach_context()
294 int widget_app_foreach_context(widget_context_cb callback, void *data);
297 * @brief Adds the system event handler.
300 * @param[out] event_handler The event handler
301 * @param[in] event_type The system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported
302 * @param[in] callback The callback function
303 * @param[in] user_data The user data to be passed to the callback function
305 * @return #WIDGET_ERROR_NONE on success,
306 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
307 * @retval #WIDGET_ERROR_NONE Successful
308 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
309 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
310 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
311 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
312 * @see app_event_type_e
313 * @see app_event_cb()
314 * @see watch_app_remove_event_handler()
316 int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type,
317 app_event_cb callback, void *user_data);
320 * @brief Removes registered event handler.
323 * @param[in] event_handler The event handler
325 * @return #WIDGET_ERROR_NONE on success,
326 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
327 * @retval #WIDGET_ERROR_NONE Successful
328 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
329 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
330 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
331 * @see watch_app_add_event_handler()
333 int widget_app_remove_event_handler(app_event_handler_h event_handler);
336 * @brief Gets a widget instance id.
339 * @param[in] context The context for widget instance
341 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
342 * @return Widget ID on success, otherwise NULL
343 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
344 * @exception #WIDGET_ERROR_FAULT Unrecoverable error
345 * @remark You must not free returned Widget ID
346 * @see get_last_result()
348 const char *widget_app_get_id(widget_context_h context);
351 * @brief Makes a class for widget instances.
354 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
355 * @param[in] callback The set of lifecycle callbacks
356 * @param[in] user_data The user data to be passed to the callback functions
357 * @return The new widget class object. NULL on error
358 * @exception #WIDGET_ERROR_NONE Successfully added
359 * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
360 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
361 * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
362 * @see get_last_result()
364 widget_class_h widget_app_class_create(widget_instance_lifecycle_callback_s callback, void *user_data);
367 * @brief Sets a tag in the context.
370 * @param[in] context The context for widget instance
371 * @param[in] tag The value to save
373 * @return #WIDGET_ERROR_NONE on success,
374 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
375 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
376 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
377 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
379 int widget_app_context_set_tag(widget_context_h context, void *tag);
382 * @brief Gets the tag in the context.
385 * @param[in] context The context for widget instance
386 * @param[out] tag The value to get
387 * @return #WIDGET_ERROR_NONE on success,
388 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
389 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
390 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
391 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
393 int widget_app_context_get_tag(widget_context_h context, void **tag);
396 * @brief Sets the content info to the widget.
398 * @param[in] context The context for widget instance
399 * @param[in] content_info The data set to save
400 * @return #WIDGET_ERROR_NONE on success,
401 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
402 * @retval #WIDGET_ERROR_NONE Successfully sent
403 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
404 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
405 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
406 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
408 int widget_app_context_set_content_info(widget_context_h context, bundle *content_info);
411 * @brief Sends the title to the widget.
413 * @param[in] context The context for widget instance
414 * @param[in] title When an accessibility mode is turned on, this string will be read
415 * @return #WIDGET_ERROR_NONE on success,
416 * otherwise an error code (see WIDGET_ERROR_XXX) on failure
417 * @retval #WIDGET_ERROR_NONE Successfully sent
418 * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
419 * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
420 * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
421 * @retval #WIDGET_ERROR_FAULT Unrecoverable error
423 int widget_app_context_set_title(widget_context_h context, const char *title);
426 * @brief Adds an additional widget class for multi-class of widget instantiation.
428 * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section.
429 * @param[in] widget_class The result of widget_app_class_create()
430 * @param[in] class_id The class id of provider
431 * @param[in] callback The set of lifecycle callbacks
432 * @param[in] user_data The user data to be passed to the callback functions
433 * @return The new widget class object. NULL on error
434 * @exception #WIDGET_ERROR_NONE Successfully added
435 * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported
436 * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
437 * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
438 * @see get_last_result()
440 widget_class_h widget_app_class_add(widget_class_h widget_class, const char *class_id,
441 widget_instance_lifecycle_callback_s callback, void *user_data);
451 #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */