X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=include%2Fwidget_app.h;h=9e309d2ac7766bef658445358fc62576b9a5122a;hb=948b351ba2463236fdb977c145d7abe55e63213f;hp=3c935cdc045bb5c9f3a084f82c1a7907030fff10;hpb=f23e0188ab8db88c7d98391f1e4b451a8cd02951;p=platform%2Fcore%2Fappfw%2Fappcore-widget.git diff --git a/include/widget_app.h b/include/widget_app.h index 3c935cd..9e309d2 100755 --- a/include/widget_app.h +++ b/include/widget_app.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2015 - 2016 Samsung Electronics Co., Ltd All Rights Reserved + * Copyright (c) 2015 - 2017 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. @@ -19,7 +19,6 @@ #define __TIZEN_APPFW_WIDGET_APP_H__ #include -#include #include #include #include @@ -33,40 +32,37 @@ extern "C" { * @{ */ + /** - * @brief Destroy type of widget instance. + * @brief Enumeration for destroy type of widget instance. * @since_tizen 2.3.1 */ typedef enum widget_app_destroy_type { - WIDGET_APP_DESTROY_TYPE_DEFAULT = 0x00, /**< Deleted */ - WIDGET_APP_DESTROY_TYPE_UPGRADE = 0x01, /**< Deleted for upgrading */ - WIDGET_APP_DESTROY_TYPE_UNINSTALL = 0x02, /**< Deleted by uninstalling */ - WIDGET_APP_DESTROY_TYPE_TERMINATE = 0x03, /**< Deleted for reboot device */ - WIDGET_APP_DESTROY_TYPE_FAULT = 0x04, /**< Deleted by system-fault */ - WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x05, /**< Temporarly deleted, will be created again */ - WIDGET_APP_DESTROY_TYPE_UNKNOWN = 0x06 /**< Undefined reason */ -} widget_app_destroy_type_e; /**< Delete type */ + WIDGET_APP_DESTROY_TYPE_PERMANENT = 0x00, /**< User deleted this widget from the viewer */ + WIDGET_APP_DESTROY_TYPE_TEMPORARY = 0x01, /**< Widget is deleted because of other reasons (e.g. widget process is terminated temporarily by the system) */ +} widget_app_destroy_type_e; + /** - * @brief The handle for widget class. + * @brief The widget class handle. * @since_tizen 2.3.1 */ typedef struct _widget_class *widget_class_h; + /** - * @brief The handle for widget context. + * @brief The widget context handle. * @since_tizen 2.3.1 */ typedef struct _widget_context *widget_context_h; + /** * @brief Called when the widget instance starts. - * @since_tizen 2.3.1 - * * @details The callback function is called after widget instance is created. * In this callback, you can initialize resources for this instance. - * - * @param[in] context The context of widget instance. + * @since_tizen 2.3.1 + * @param[in] context The context of widget instance * @param[in] content The data set for the previous status * @param[in] w The pixel value for widget width * @param[in] h The pixel value for widget height @@ -77,37 +73,34 @@ typedef struct _widget_context *widget_context_h; */ typedef int (*widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data); + /** * @brief Called before the widget instance is destroyed. - * @since_tizen 2.3.1 - * * @details The callback function is called before widget instance is destroyed. * In this callback, you can finalize resources for this instance. - * If reason is not #WIDGET_APP_DESTROY_TYPE_DEFAULT, It should store the current status by using incoming bundle. - * - * @param[in] context The context of widget instance. - * @param[in] reason The reason for destruction - * @param[in,out] content The data set to save - * @param[in] user_data The user data passed from widget_app_class_create function + * If reason is not #WIDGET_APP_DESTROY_TYPE_TEMPORARY, it should store the current status by using incoming bundle. + * @since_tizen 2.3.1 * @remark Note that the parameter 'content' is used to save the status of the widget instance. * As a input parameter, content contains the saved status of the widget instance. * You can fill the content parameter with the current status in this callback, * then the framework will save the content by receiving it as a output parameter. * Consequently, you should not use widget_app_context_set_content_info() api in this callback. * The content will be overwritten after this callback returns with the 'content' parameter. - * + * @param[in] context The context of widget instance + * @param[in] reason The reason for destruction + * @param[in,out] content The data set to save + * @param[in] user_data The user data passed from widget_app_class_create function * @return #WIDGET_ERROR_NONE on success, * otherwise an error code (see WIDGET_ERROR_XXX) on failure */ typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data); + /** * @brief Called when the widget is invisible. - * @since_tizen 2.3.1 - * * @details The callback function is called when the widget is invisible. * The paused instance may be destroyed by framework. - * + * @since_tizen 2.3.1 * @param[in] context The context of widget instance * @param[in] user_data The user data passed from widget_app_class_create function * @return #WIDGET_ERROR_NONE on success, @@ -115,12 +108,11 @@ typedef int (*widget_instance_destroy_cb)(widget_context_h context, widget_app_d */ typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_data); + /** * @brief Called when the widget is visible. - * @since_tizen 2.3.1 - * * @details The callback function is called when the widget is visible. - * + * @since_tizen 2.3.1 * @param[in] context The context of widget instance * @param[in] user_data The user data passed from widget_app_class_create function * @return #WIDGET_ERROR_NONE on success, @@ -128,12 +120,11 @@ typedef int (*widget_instance_pause_cb)(widget_context_h context, void *user_dat */ typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_data); + /** * @brief Called before the widget size is changed. - * @since_tizen 2.3.1 - * * @details The callback function is called before the widget size is changed. - * + * @since_tizen 2.3.1 * @param[in] context The context of widget instance * @param[in] w The pixel value for widget width * @param[in] h The pixel value for widget height @@ -143,13 +134,12 @@ typedef int (*widget_instance_resume_cb)(widget_context_h context, void *user_da */ typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data); + /** * @brief Called when the event for updating widget is received. - * @since_tizen 2.3.1 - * * @details The callback function is called when the event for updating widget is received. - * - * @param[in] context The context of widget instance. + * @since_tizen 2.3.1 + * @param[in] context The context of widget instance * @param[in] content The data set for updating this widget. It will be provided by requester. * Requester can use widget_service_trigger_update() * @param[in] force Although the widget is paused, if it is TRUE, the widget can be updated @@ -160,8 +150,9 @@ typedef int (*widget_instance_resize_cb)(widget_context_h context, int w, int h, */ typedef int (*widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data); + /** - * @brief The structure for lifecycle of a widget instance. + * @brief The structure type containing the set of callback functions for lifecycle of a widget instance. * @since_tizen 2.3.1 */ typedef struct { @@ -173,14 +164,13 @@ typedef struct { widget_instance_update_cb update; /**< The callback function is called when the event for updating widget is received. */ } widget_instance_lifecycle_callback_s; + /** * @brief Called when the application starts. - * @since_tizen 2.3.1 - * * @details The callback function is called before the main loop of the application starts. * In this callback, you can initialize resources which can be shared among widget instances. * This function should return the handle for widget class so that it will be used for making instances of widget. - * + * @since_tizen 2.3.1 * @param[in] user_data The user data passed from the callback registration function * @return The object of widget class * @see widget_app_main() @@ -197,17 +187,18 @@ typedef struct { */ typedef widget_class_h (*widget_app_create_cb)(void *user_data); + /** * @brief Called when the application's main loop exits. * @details This callback function is called once after the main loop of the application exits. * You should release the application's resources in this function. * @since_tizen 2.3.1 - * * @param[in] user_data The user data passed from the callback registration function * @see widget_app_main() */ typedef void (*widget_app_terminate_cb)(void *user_data); + /** * @brief The structure for lifecycle of a widget application. * @since_tizen 2.3.1 @@ -217,31 +208,29 @@ typedef struct { widget_app_terminate_cb terminate; /**< This callback function is called once after the main loop of the application exits. */ } widget_app_lifecycle_callback_s; + /** * @brief Called for each widget context. - * @since_tizen 2.3.1 - * * @details This function will be called in the function of widget_app_foreach_context repeatedly. - * + * @since_tizen 2.3.1 * @param[in] context The context for widget instance * @param[in] data The data for caller - * @return true to continue with the next iteration of the loop, - * otherwise false to break out of the loop. + * @return @c true to continue with the next iteration of the loop, + * otherwise @c false to break out of the loop * @see widget_app_foreach_context() */ typedef bool (*widget_context_cb)(widget_context_h context, void *data); + /** * @brief Runs the main loop of the application until widget_app_exit() is called. * @since_tizen 2.3.1 - * * @param[in] argc The argument count * @param[in] argv The argument vector * @param[in] callback The set of callback functions to handle application events * @param[in] user_data The user data to be passed to the callback functions - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported @@ -250,13 +239,13 @@ typedef bool (*widget_context_cb)(widget_context_h context, void *data); */ int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data); + /** * @brief Exits the main loop of the application. * @details The main loop of the application stops and widget_app_terminate_cb() is invoked. * @since_tizen 2.3.1 - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported * @retval #WIDGET_ERROR_FAULT Unrecoverable error @@ -265,14 +254,13 @@ int widget_app_main(int argc, char **argv, widget_app_lifecycle_callback_s *call */ int widget_app_exit(void); + /** * @brief Finishes context for the widget instance. * @since_tizen 2.3.1 - * * @param[in] context The context for widget instance - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported @@ -280,15 +268,14 @@ int widget_app_exit(void); */ int widget_app_terminate_context(widget_context_h context); + /** * @brief Retrieves all widget contexts in this application. * @since_tizen 2.3.1 - * * @param[in] callback The iteration callback function * @param[in] data The data for the callback function - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_CANCELED The iteration is canceled @@ -298,17 +285,16 @@ int widget_app_terminate_context(widget_context_h context); */ int widget_app_foreach_context(widget_context_cb callback, void *data); + /** * @brief Adds the system event handler. * @since_tizen 2.3.1 - * * @param[out] event_handler The event handler * @param[in] event_type The system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported * @param[in] callback The callback function * @param[in] user_data The user data to be passed to the callback function - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory @@ -324,11 +310,9 @@ int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_t /** * @brief Removes registered event handler. * @since_tizen 2.3.1 - * * @param[in] event_handler The event handler - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported @@ -337,73 +321,81 @@ int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_t */ int widget_app_remove_event_handler(app_event_handler_h event_handler); + /** * @brief Gets a widget instance id. * @since_tizen 2.3.1 - * - * @param[in] context The context for widget instance - * * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section. - * @return Widget ID on success, otherwise NULL + * @remark You must not free returned widget instance id + * @remark The returned widget instance id is volatile. If the device reboots or the widget's process restarts, it will be changed.\n + * So, you should not assume this value is a persistent one. + * @remark widget_service_trigger_update(), widget_service_change_period(), widget_service_get_content_of_widget_instance()\n + * can be called with returned instance id. + * @param[in] context The context for widget instance + * @return widget instance id on success, + * otherwise NULL * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported * @exception #WIDGET_ERROR_FAULT Unrecoverable error - * @remark You must not free returned Widget ID * @see get_last_result() + * @see widget_service_trigger_update() + * @see widget_service_change_period() + * @see widget_service_get_content_of_widget_instance() */ const char *widget_app_get_id(widget_context_h context); + /** * @brief Makes a class for widget instances. * @since_tizen 2.3.1 - * * @remarks The specific error code can be obtained using the get_last_result() method. Error codes are described in Exception section. * @param[in] callback The set of lifecycle callbacks * @param[in] user_data The user data to be passed to the callback functions - * @return The new widget class object. NULL on error + * @return The new widget class object, + * NULL on error * @exception #WIDGET_ERROR_NONE Successfully added - * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported + * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory * @see get_last_result() */ widget_class_h widget_app_class_create(widget_instance_lifecycle_callback_s callback, void *user_data); + /** * @brief Sets a tag in the context. * @since_tizen 2.3.1 - * * @param[in] context The context for widget instance * @param[in] tag The value to save - * * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_FAULT Unrecoverable error */ int widget_app_context_set_tag(widget_context_h context, void *tag); + /** * @brief Gets the tag in the context. * @since_tizen 2.3.1 - * * @param[in] context The context for widget instance * @param[out] tag The value to get * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_FAULT Unrecoverable error */ int widget_app_context_get_tag(widget_context_h context, void **tag); + /** * @brief Sets the content info to the widget. * @since_tizen 2.3.1 * @param[in] context The context for widget instance * @param[in] content_info The data set to save * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successfully sent * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported @@ -412,13 +404,14 @@ int widget_app_context_get_tag(widget_context_h context, void **tag); */ int widget_app_context_set_content_info(widget_context_h context, bundle *content_info); + /** * @brief Sends the title to the widget. * @since_tizen 2.3.1 * @param[in] context The context for widget instance * @param[in] title When an accessibility mode is turned on, this string will be read * @return #WIDGET_ERROR_NONE on success, - * otherwise an error code (see WIDGET_ERROR_XXX) on failure + * otherwise an error code (see WIDGET_ERROR_XXX) on failure * @retval #WIDGET_ERROR_NONE Successfully sent * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported @@ -427,6 +420,7 @@ int widget_app_context_set_content_info(widget_context_h context, bundle *conten */ int widget_app_context_set_title(widget_context_h context, const char *title); + /** * @brief Adds an additional widget class for multi-class of widget instantiation. * @since_tizen 3.0 @@ -435,9 +429,10 @@ int widget_app_context_set_title(widget_context_h context, const char *title); * @param[in] class_id The class id of provider * @param[in] callback The set of lifecycle callbacks * @param[in] user_data The user data to be passed to the callback functions - * @return The new widget class object. NULL on error + * @return The new widget class object, + * NULL on error * @exception #WIDGET_ERROR_NONE Successfully added - * @exception #WIDGET_ERROR_INVALID_PARAMETER Not supported + * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported * @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory * @see get_last_result() @@ -454,4 +449,3 @@ widget_class_h widget_app_class_add(widget_class_h widget_class, const char *cla #endif #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */ -