From 3be5a3fd119e14a5834a1e946b1298f2a4ed5922 Mon Sep 17 00:00:00 2001 From: Daehyeon Jung Date: Fri, 16 Dec 2016 18:14:20 +0900 Subject: [PATCH] fix API description Change-Id: Ic83954f5ded30d25949b24e07afb708a9737c6d1 --- doc/appcore-widget_doc.h | 43 ++++++++---------- include/widget_app.h | 115 ++++++++++++++++++++++------------------------- include/widget_app_efl.h | 15 ++++--- 3 files changed, 81 insertions(+), 92 deletions(-) diff --git a/doc/appcore-widget_doc.h b/doc/appcore-widget_doc.h index 1a83d63..99b698c 100755 --- a/doc/appcore-widget_doc.h +++ b/doc/appcore-widget_doc.h @@ -14,28 +14,26 @@ * limitations under the License. */ + /** - * * @ingroup CAPI_WIDGET_FRAMEWORK * @defgroup CAPI_WIDGET_APP_MODULE Widget Application - * @brief Widget application API - * + * @brief Widget application API. * @section CAPI_WIDGET_APP_MODULE_HEADER Required Header - * \#include - * \#include + * \#include + * \#include + * * @section CAPI_WIDGET_APP_MODULE_OVERVIEW Overview * The @ref CAPI_WIDGET_APP_MODULE API provides functions for handling Tizen widget application state changes or system events. Tizen widget application can be shown in the home screen. - * This APIs support making multiple widget instances per an application. - * + * This API supports making multiple widget instances per an application. * This API provides interfaces for the following categories: - * - Starting or exiting the main event loop - * - Registering callbacks for application state change events - * - Registering callbacks for basic system events - * - Registering callbacks for instance state change events + * - Starting or exiting the main event loop. + * - Registering callbacks for application state change events. + * - Registering callbacks for basic system events. + * - Registering callbacks for instance state change events. * * @subsection CAPI_WIDGET_APP_MODULE_STATE_CHANGE_EVENT Registering Callbacks for Application State Change Events - * As for Tizen widget application states, it is very simple and somewhat similer to Tizen service application states. - * + * As for Tizen widget application states, it is very simple and somewhat similar to Tizen service application states. *

* * @@ -46,7 +44,7 @@ * * * @@ -54,24 +52,23 @@ * * * *
widget_app_create_cb()Hook to take necessary actions before the main event loop starts. * Your UI generation code should be placed here so that you do not miss any events from your application UI. - * Please make sure that you should make a class handle and return it. It will be used when the event for creating widget instance is received. + * Please make sure that you make a class handle and return it. It will be used when the event for creating widget instance is received. * You can initialize shared resources for widget instances in this callback function as well. *
widget_app_terminate_cb() Hook to take necessary actions when your application is terminating. * Your application should release all resources, especially any - * allocations and shared resources must be freed here so other running applications can fully use these shared resources. + * allocations and shared resources must be freed here so that other running applications can fully use these shared resources. *
*

- * * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition. + * * @image html widget_app_lifecycle.png "Widget Application States" * * @subsection CAPI_WIDGET_APP_MODULE_SYSTEM_EVENT Registering Callbacks for System Events - * Tizen widget applications can receive system events with widget_app_add_event_handler() api. + * Tizen widget applications can receive system events with widget_app_add_event_handler() API. * The type of system events that can be received are same as Tizen UI applications except for APP_EVENT_DEVICE_ORIENTATION_CHANGED. * See @ref CAPI_APPLICATION_MODULE. * The event for APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported in this module. - * + * @subsection CAPI_WIDGET_APP_INSTNACE_STATE_CHANGE_EVENT Registering callbacks for instance state change events - * As for Tizen widget instance states, it is somewhat similer to Tizen application states. - * + * As for Tizen widget instance states, it is somewhat similar to Tizen application states. *

* * @@ -82,7 +79,7 @@ * * * * @@ -117,13 +114,11 @@ * *
widget_instance_create_cb() Called after widget instance is created. * In this callback, you can initialize resources for this instance. - * If parameter 'content' is not NULL, You should restore the pervious status. + * If parameter 'content' is not NULL, you should restore the pervious status. *
*

- * * Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition. + * * @image html widget_obj_lifecycle.png "Widget Instance States" * * @section CAPI_WIDGET_APP_MODULE_RELATED_FEATURES Related Features * This API is related with the following feature: * - http://tizen.org/feature/shell.appwidget - * - * */ diff --git a/include/widget_app.h b/include/widget_app.h index 3cd38a0..da53d6b 100755 --- a/include/widget_app.h +++ b/include/widget_app.h @@ -33,6 +33,7 @@ extern "C" { * @{ */ + /** * @brief Destroy type of widget instance. * @since_tizen 2.3.1 @@ -40,28 +41,29 @@ extern "C" { typedef enum widget_app_destroy_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; +} widget_app_destroy_type_e; /**< Delete type */ + /** - * @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. + * @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 @@ -72,37 +74,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_TEMPORARY, 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. * @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. - * * @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, @@ -110,12 +109,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. - * * @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, @@ -123,12 +121,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. - * * @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 @@ -138,13 +135,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. + * @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 @@ -155,6 +151,7 @@ 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. * @since_tizen 2.3.1 @@ -168,14 +165,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. - * * @param[in] user_data The user data passed from the callback registration function * @return The object of widget class * @see widget_app_main() @@ -192,17 +188,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 @@ -212,31 +209,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. - * * @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 @@ -245,13 +240,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 @@ -260,14 +255,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 @@ -275,15 +269,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 @@ -293,17 +286,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 @@ -319,11 +311,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 + * @return #WIDGET_ERROR_NONE on success + * 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 @@ -332,25 +322,25 @@ 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 ID + * @param[in] context The context for widget instance + * @return Widget 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() */ 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 @@ -363,42 +353,42 @@ const char *widget_app_get_id(widget_context_h context); */ 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 @@ -407,13 +397,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 @@ -422,6 +413,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 @@ -449,4 +441,3 @@ widget_class_h widget_app_class_add(widget_class_h widget_class, const char *cla #endif #endif /* __TIZEN_APPFW_WIDGET_APP_H__ */ - diff --git a/include/widget_app_efl.h b/include/widget_app_efl.h index fd1a0c0..092f195 100644 --- a/include/widget_app_efl.h +++ b/include/widget_app_efl.h @@ -14,6 +14,7 @@ * limitations under the License. */ + #ifndef __TIZEN_APPFW_WIDGET_APP_EFL_H__ #define __TIZEN_APPFW_WIDGET_APP_EFL_H__ @@ -24,30 +25,32 @@ extern "C" { #endif + /** * @addtogroup CAPI_WIDGET_APP_MODULE * @{ */ /** - * @brief Gets a evas object for the widget + * @brief Gets an Evas object for the widget. * @since_tizen 2.3.1 - * * @param[in] context The context for widget instance - * @param[out] win Evas object for window - * - * @return 0 on success, otherwise a negative error value - * @retval #WIDGET_ERROR_NONE Successfull + * @param[out] win evas object for window + * @return 0 on success, + * otherwise a negative error value + * @retval #WIDGET_ERROR_NONE Successful * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter * @retval #WIDGET_ERROR_FAULT Failed to make evas object * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported */ int widget_app_get_elm_win(widget_context_h context, Evas_Object **win); + /** * @} */ + #ifdef __cplusplus } #endif -- 2.7.4