/*
- * 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.
#define __TIZEN_APPFW_WIDGET_APP_H__
#include <tizen.h>
-#include <app_control.h>
#include <app_common.h>
#include <bundle.h>
#include <widget_errno.h>
/**
- * @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_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; /**< Delete type */
+} widget_app_destroy_type_e;
/**
/**
* @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.
+ * @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
- * @param[in] user_data The user data passed from widget_app_class_create function
+ * @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
/**
* @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.
- * @remark Note that the parameter 'content' is used to save the status of the widget instance.
+ * @since_tizen 2.3.1
+ * @remarks 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.
+ * Consequently, you should not use widget_app_context_set_content_info() function 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
+ * @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
*/
/**
* @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
+ * @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
*/
/**
* @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
+ * @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
*/
/**
* @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
- * @param[in] user_data The user data passed from widget_app_class_create function
+ * @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
*/
/**
* @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.
+ * @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
- * @param[in] user_data The user data passed from widget_app_class_create function
+ * @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
* @see widget_service_trigger_update()
/**
- * @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 {
/**
* @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()
/**
* @brief Called for each widget context.
+ * @details This function will be called in the function of widget_app_foreach_context() repeatedly.
* @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
+ * @param[in] user_data The data for caller
* @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);
+typedef bool (*widget_context_cb)(widget_context_h context, void *user_data);
/**
* @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
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
* @see widget_app_exit()
*/
* @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
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
*/
int widget_app_terminate_context(widget_context_h context);
* @return #WIDGET_ERROR_NONE on success,
* 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_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_CANCELED The iteration is canceled
- * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
- * @see widget_app_foreach_context()
+ * @see widget_context_cb()
*/
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] 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
* @retval #WIDGET_ERROR_NONE Successful
+ * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
- * @retval #WIDGET_ERROR_NOT_SUPPORTED Not supported
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
* @see app_event_type_e
* @see app_event_cb()
- * @see watch_app_remove_event_handler()
+ * @see widget_app_remove_event_handler()
*/
int widget_app_add_event_handler(app_event_handler_h *event_handler, app_event_type_e event_type,
app_event_cb callback, void *user_data);
* @brief Removes registered event handler.
* @since_tizen 2.3.1
* @param[in] event_handler The event handler
- * @return #WIDGET_ERROR_NONE on success
+ * @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
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
- * @see watch_app_add_event_handler()
+ * @see widget_app_add_event_handler()
*/
int widget_app_remove_event_handler(app_event_handler_h event_handler);
* @brief Gets a widget instance id.
* @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.
- * @remark You must not free returned Widget ID
+ * @remarks You must not free returned widget instance id
+ * @remarks 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.
+ * @remarks 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 ID on success,
- * otherwise NULL
+ * @return widget instance id on success,
+ * otherwise NULL
+ * @exception #WIDGET_ERROR_NONE Successful
* @exception #WIDGET_ERROR_NOT_SUPPORTED Not supported
+ * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @exception #WIDGET_ERROR_FAULT Unrecoverable error
* @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);
* @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_NOT_SUPPORTED Not supported
+ * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
* @see get_last_result()
*/
* @param[in] tag The value to save
* @return #WIDGET_ERROR_NONE on success,
* 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_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
* @param[out] tag The value to get
* @return #WIDGET_ERROR_NONE on success,
* 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_INVALID_PARAMETER Invalid parameter
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
* @return #WIDGET_ERROR_NONE on success,
* 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
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
*/
* @return #WIDGET_ERROR_NONE on success,
* 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
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
* @retval #WIDGET_ERROR_FAULT Unrecoverable error
*/
* @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_NOT_SUPPORTED Not supported
+ * @exception #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter
* @exception #WIDGET_ERROR_OUT_OF_MEMORY Out of memory
* @see get_last_result()
*/