* limitations under the License.
*/
+
#ifndef __WIDGET_SERVICE_DOC_H__
#define __WIDGET_SERVICE_DOC_H__
+
/**
- * @defgroup CAPI_WIDGET_FRAMEWORK Widget
* @ingroup CAPI_APPLICATION_FRAMEWORK
+ * @defgroup CAPI_WIDGET_FRAMEWORK Widget
* @section CAPI_WIDGET_FRAMEWORK_OVERVIEW Overview
-<table>
-<tr>
-<th>API </th><th>Description </th></tr>
-<tr>
-<td><a class="el" href="group__CAPI__WIDGET__APP__MODULE.html">Widget Application</a> </td>
-<td>Provides functions for handling Tizen widget application state changes or system events. </td>
-</tr>
-<tr>
-<td><a class="el" href="group__CAPI__WIDGET__SERVICE__MODULE.html">Widget Service</a> </td>
-<td>Provides functions to get the information of installed widgets.</td>
-</tr>
-<tr>
-<td><a class="el" href="group__CAPI__WIDGET__VIEWER__EVAS__MODULE.html">Widget Viewer Evas</a> </td>
-<td>Provides functions to replace and handle instances of widgets EFL application.</td>
-</tr>
-<tr>
-<td><a class="el" href="group__dali__widget__view.html">Widget Viewer Dali</a> </td>
-<td>Provides functions to replace and handle instances of widgets for DALi application.</td>
-</tr>
-</table>
+ <tr>
+ <th>API </th><th>Description </th></tr>
+ <tr>
+
<td><a class="el" href="group__CAPI__WIDGET__APP__MODULE.html">Widget Application</a> </td>
+ <td>Provides functions for handling Tizen widget application state changes or system events. </td>
+ </tr>
+ <tr>
+
<td><a class="el" href="group__CAPI__WIDGET__SERVICE__MODULE.html">Widget Service</a> </td>
+ <td>Provides functions to get the information of installed widgets.</td>
+ </tr>
+ <tr>
+
<td><a class="el" href="group__CAPI__WIDGET__VIEWER__EVAS__MODULE.html">Widget Viewer Evas</a> </td>
+ <td>Provides functions to replace and handle instances of widgets EFL application.</td>
+ </tr>
+ <tr>
+
<td><a class="el" href="group__dali__widget__view.html">Widget Viewer Dali</a> </td>
+ <td>Provides functions to replace and handle instances of widgets for DALi application.</td>
+ </tr>
+ </table>
*/
+
/**
- * @defgroup CAPI_WIDGET_SERVICE_MODULE Widget Service
- * @brief To get the information of installed widgets
* @ingroup CAPI_WIDGET_FRAMEWORK
+ * @defgroup CAPI_WIDGET_SERVICE_MODULE Widget Service
+ * @brief To get the information of installed widgets.
* @section CAPI_WIDGET_SERVICE_MODULE_HEADER Required Header
- * \#include <widget_service.h>
- * \#include <widget_errno.h>
+ * \#include <widget_service.h>
+ * \#include <widget_errno.h>
+ *
* @section CAPI_WIDGET_SERVICE_MODULE_FEATURE Related Features
* This API is related with the following feature:
* - http://tizen.org/feature/shell.appwidget
- * @section CAPI_WIDGET_SERVICE_MODULE_OVERVIEW Overview
-<H1>1. widget service API</H1>
-Tizen supports various kinds of API set for retrieving information of widgets.
-Every widgets are installed via package manager utilities.
-The information of installed widgets are stored in the system DB.
-
-In some cases, application developer needs to send update request to some widgets.
-To make it possible, this module provides related API set.
-But the API will only works if the widget and application are packaged in one.
-
-<H2>1.1 APIs for retrieving information of widgets</H2>
-
-To get the information for installed widgets.
-
-<H2>1.2 APIs for communicating with running widget instances</H2>
-
-To trigger the update event or send the updated content string to the widget.
-
-<H1>2. Size of widget</H1>
-
-Widget has predefined size types.
-1x1 is a square so its pixel size of width and height must has to be same.
-2x2, 4x4 also sqaure.
-
-2x1, 4x1, 4x2, 4x3 is a rectangle. so its pixel size of width & height should not be same.
-pixel size of width should be long than height.
-
-Pixel size can be differ between different devices.
-It depends on its screen resolution.
-
-So widget developer should care various kinds of devices (has different screen resolution).
-
-<TABLE>
-<TR>
-<TD>Size Type</TD><TD>Size in pixels</TD><TD>Supported profile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_1x1</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>No profile - This size type is not used. just defined for specifying a default cell size</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_2x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_2x2</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile, Wearable (Default size)</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_4x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_4x2</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_4x3</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_4x4</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-</TABLE>
-
-Widget also works for Easy Mode.
-For the Easy Mode, there are different size types.
-Called WIDGET_SIZE_TYPE_EASY_NxM
-
-<TABLE>
-<TR>
-<TD>Size Type</TD><TD>Size in pixels</TD><TD>Supported profile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_EASY_1x1</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_EASY_3x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-<TR>
-<TD>WIDGET_SIZE_TYPE_EASY_3x3</TD><TD> - (SQARE - depends on screen resolution) </TD><TD>Mobile</TD>
-</TR>
-</TABLE>
-
-However the Easy Mode is not a mandatory requirements for viewer application development.
-So you will not be able to create your widgets using Easy Mode size types.
-But if you are developing the homescreen(or application which is related with widgets displaying),
-You should care these types too.
-
*
+ * @section CAPI_WIDGET_SERVICE_MODULE_OVERVIEW Overview
+ <H1>1. widget service API</H1>
+ Tizen supports various kinds of APIs set for retrieving information of widgets.
+ Every widgets are installed via package manager utilities.
+ The information of installed widgets are stored in the system DB.
+ In some cases, application developer needs to send update request to some widgets.
+ To make it possible, this module provides related API set.
+ But the API will only works if the widget and application are packaged in one.
+ <H2>1.1 APIs for retrieving information of widgets</H2>
+ To get the information for installed widgets.
+ <H2>1.2 APIs for communicating with running widget instances</H2>
+ To trigger the update event or send the updated content string to the widget.
+ <H1>2. Size of widget</H1>
+ Widget has predefined size types.
+ 1x1 is a square so its pixel size of width and height must has to be same.
+ 2x2, 4x4 also sqaure.
+ 2x1, 4x1, 4x2, 4x3 is a rectangle. so its pixel size of width & height should not be same.
+ pixel size of width should be long than height.
+ Pixel size can be differ between different devices.
+ It depends on its screen resolution.
+ So widget developer should care various kinds of devices (has different screen resolution).
+ <TABLE>
+ <TR>
+ <TD>Size Type</TD><TD>Size in pixels</TD><TD>Supported profile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_1x1</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>No profile - This size type is not used. just defined for specifying a default cell size</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_2x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_2x2</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile, Wearable (Default size)</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_4x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_4x2</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_4x3</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_4x4</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ </TABLE>
+ Widget also works for Easy Mode.
+ For the Easy Mode, there are different size types.
+ Called WIDGET_SIZE_TYPE_EASY_NxM
+ <TABLE>
+ <TR>
+ <TD>Size Type</TD><TD>Size in pixels</TD><TD>Supported profile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_EASY_1x1</TD><TD> - (SQUARE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_EASY_3x1</TD><TD> - (RECTANGLE, depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ <TR>
+ <TD>WIDGET_SIZE_TYPE_EASY_3x3</TD><TD> - (SQARE - depends on screen resolution) </TD><TD>Mobile</TD>
+ </TR>
+ </TABLE>
+ However the Easy Mode is not a mandatory requirements for viewer application development.
+ So you will not be able to create your widgets using Easy Mode size types.
+ But if you are developing the homescreen(or application which is related with widgets displaying),
+ You should care these types too.
*/
+
#endif
* @{
*/
+
/**
* @brief Enumeration for list of supporting widget size types.
* @since_tizen 2.3.1
*/
typedef enum widget_size_type {
- WIDGET_SIZE_TYPE_1x1 = 0x0001, /**< 175x175 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_2x1 = 0x0002, /**< 354x175 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_2x2 = 0x0004, /**< 354x354 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x1 = 0x0008, /**< 712x175 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x2 = 0x0010, /**< 712x354 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x3 = 0x0020, /**< 712x533 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x4 = 0x0040, /**< 712x712 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x5 = 0x0080, /**< 712x891 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_4x6 = 0x0100, /**< 712x1070 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_1x1 = 0x0001, /**< 175x175 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_2x1 = 0x0002, /**< 354x175 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_2x2 = 0x0004, /**< 354x354 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x1 = 0x0008, /**< 712x175 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x2 = 0x0010, /**< 712x354 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x3 = 0x0020, /**< 712x533 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x4 = 0x0040, /**< 712x712 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x5 = 0x0080, /**< 712x891 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_4x6 = 0x0100, /**< 712x1070 based on 720x1280 resolution */
WIDGET_SIZE_TYPE_EASY_1x1 = 0x1000, /**< 224x215 based on 720x1280 resolution */
WIDGET_SIZE_TYPE_EASY_3x1 = 0x2000, /**< 680x215 based on 720x1280 resolution */
WIDGET_SIZE_TYPE_EASY_3x3 = 0x4000, /**< 680x653 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_FULL = 0x0800, /**< 720x1280 based on 720x1280 resolution */
- WIDGET_SIZE_TYPE_UNKNOWN = 0xFFFF /**< Error case */
+ WIDGET_SIZE_TYPE_FULL = 0x0800, /**< 720x1280 based on 720x1280 resolution */
+ WIDGET_SIZE_TYPE_UNKNOWN = 0xFFFF /**< Error case */
} widget_size_type_e;
+
/**
* @brief Enumeration for widget event type.
* @details These events will be sent from the provider.
* @since_tizen 2.3.1
*/
-
typedef enum widget_event_type {
- WIDGET_EVENT_WIDGET_UPDATED = 0, /**< Contents of the given widget is updated */
+ WIDGET_EVENT_WIDGET_UPDATED = 0, /**< Contents of the given widget is updated */
WIDGET_EVENT_WIDGET_EXTRA_UPDATED = 1,
- WIDGET_EVENT_CREATED = 4, /**< A new widget is created */
- WIDGET_EVENT_DELETED = 5, /**< A widget is deleted */
- WIDGET_EVENT_PERIOD_CHANGED = 8, /**< Update period is changed */
- WIDGET_EVENT_WIDGET_SIZE_CHANGED = 9, /**< widget size is changed */
- WIDGET_EVENT_EXTRA_INFO_UPDATED = 21, /**< Extra information is updated */
- WIDGET_EVENT_IGNORED = 0xFF /**< Request is ignored */
+ WIDGET_EVENT_CREATED = 4, /**< A new widget is created */
+ WIDGET_EVENT_DELETED = 5, /**< A widget is deleted */
+ WIDGET_EVENT_PERIOD_CHANGED = 8, /**< Update period is changed */
+ WIDGET_EVENT_WIDGET_SIZE_CHANGED = 9, /**< widget size is changed */
+ WIDGET_EVENT_EXTRA_INFO_UPDATED = 21, /**< Extra information is updated */
+ WIDGET_EVENT_IGNORED = 0xFF /**< Request is ignored */
} widget_event_type_e;
+
/**
* @brief Gets the pixel size of given size type.
- * @details
- * Size types would be\n
- * #WIDGET_SIZE_TYPE_1x1\n
- * #WIDGET_SIZE_TYPE_2x1\n
- * #WIDGET_SIZE_TYPE_2x2\n
- * #WIDGET_SIZE_TYPE_4x1\n
- * #WIDGET_SIZE_TYPE_4x2\n
- * #WIDGET_SIZE_TYPE_4x3\n
- * #WIDGET_SIZE_TYPE_4x4\n
- * #WIDGET_SIZE_TYPE_4x5\n
- * #WIDGET_SIZE_TYPE_4x6\n
- * #WIDGET_SIZE_TYPE_FULL\n
- * #WIDGET_SIZE_TYPE_EASY_1x1\n
- * #WIDGET_SIZE_TYPE_EASY_3x1\n
- * #WIDGET_SIZE_TYPE_EASY_3x3.
+ * @details Size types would be\n
+ * #WIDGET_SIZE_TYPE_1x1\n
+ * #WIDGET_SIZE_TYPE_2x1\n
+ * #WIDGET_SIZE_TYPE_2x2\n
+ * #WIDGET_SIZE_TYPE_4x1\n
+ * #WIDGET_SIZE_TYPE_4x2\n
+ * #WIDGET_SIZE_TYPE_4x3\n
+ * #WIDGET_SIZE_TYPE_4x4\n
+ * #WIDGET_SIZE_TYPE_4x5\n
+ * #WIDGET_SIZE_TYPE_4x6\n
+ * #WIDGET_SIZE_TYPE_FULL\n
+ * #WIDGET_SIZE_TYPE_EASY_1x1\n
+ * #WIDGET_SIZE_TYPE_EASY_3x1\n
+ * #WIDGET_SIZE_TYPE_EASY_3x3.
* @since_tizen 2.3.1
* @param[in] type Size type
* @param[out] width Pixel size width
* @param[out] height Pixel size height
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_NONE Successfully done
* @see widget_size_type()
* @see widget_service_get_size_type()
*/
extern int widget_service_get_size(widget_size_type_e type, int *width, int *height);
+
/**
* @brief Gets the size type for given pixel size.
- * @details
- * Returnable size types are\n
- * #WIDGET_SIZE_TYPE_1x1\n
- * #WIDGET_SIZE_TYPE_2x1\n
- * #WIDGET_SIZE_TYPE_2x2\n
- * #WIDGET_SIZE_TYPE_4x1\n
- * #WIDGET_SIZE_TYPE_4x2\n
- * #WIDGET_SIZE_TYPE_4x3\n
- * #WIDGET_SIZE_TYPE_4x4\n
- * #WIDGET_SIZE_TYPE_4x5\n
- * #WIDGET_SIZE_TYPE_4x6\n
- * #WIDGET_SIZE_TYPE_FULL\n
- * #WIDGET_SIZE_TYPE_EASY_1x1\n
- * #WIDGET_SIZE_TYPE_EASY_3x1\n
- * #WIDGET_SIZE_TYPE_EASY_3x3\n
- * or\n
- * #WIDGET_SIZE_TYPE_UNKNOWN for error.
+ * @details Returnable size types are\n
+ * #WIDGET_SIZE_TYPE_1x1\n
+ * #WIDGET_SIZE_TYPE_2x1\n
+ * #WIDGET_SIZE_TYPE_2x2\n
+ * #WIDGET_SIZE_TYPE_4x1\n
+ * #WIDGET_SIZE_TYPE_4x2\n
+ * #WIDGET_SIZE_TYPE_4x3\n
+ * #WIDGET_SIZE_TYPE_4x4\n
+ * #WIDGET_SIZE_TYPE_4x5\n
+ * #WIDGET_SIZE_TYPE_4x6\n
+ * #WIDGET_SIZE_TYPE_FULL\n
+ * #WIDGET_SIZE_TYPE_EASY_1x1\n
+ * #WIDGET_SIZE_TYPE_EASY_3x1\n
+ * #WIDGET_SIZE_TYPE_EASY_3x3\n
+ * or\n
+ * #WIDGET_SIZE_TYPE_UNKNOWN for error.
* @since_tizen 2.3.1
* @param[in] width Pixel size width
* @param[in] height Pixel size height
* @param[out] size_type Widget size type\n
- * @return 0 on success, otherwise a negative error value
- * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given.
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
* @see widget_size_type()
* @see widget_service_get_size()
*/
extern int widget_service_get_size_type(int width, int height, widget_size_type_e *size_type);
+
/**
* @brief Gets the need of mouse event for the given widget.
* @details This function gets need of mouse event for the given widget from database.\n
- * The value of mouse event requirement means... \n
- * true : The widget requires mouse event. A viewer must has to feed the mouse event to the widget instance\n
- * false : The widget doesn't require mouse event.\n
+ * The value of mouse event requirement means: \n
+ * true : The widget requires mouse event. A viewer must feed the mouse event to the widget instance.\n
+ * false : The widget doesn't require mouse event.\n
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @param[in] widget_id appid of widget application
- * @param[in] size_type widget size type
- * @param[out] need_of_mouse_event the need of mouse event
- * @return 0 on success, otherwise a negative error value
- * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given.
- * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file.
+ * @param[in] size_type Widget size type
+ * @param[out] need_of_mouse_event The need of mouse event
+ * @return 0 on success,
+ * otherwise a negative error value
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
+ * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
* @see widget_size_type_e
* @see widget_service_get_need_of_touch_effect()
* @see widget_service_get_need_of_frame()
*/
extern int widget_service_get_need_of_mouse_event(const char *widget_id, widget_size_type_e size_type, bool *need_of_mouse_event);
+
/**
* @brief Gets the need of touch effect for the given widget.
* @details This API gets the need of touch effect for the given widget from database.\n
- * The value of the need of touch effect means... \n
- * true : A viewer is required to make the touch effect when a user click the widget, but it is just recommendation.\n
- * false : A viewer is not required to make the touch effect, the box will make touch effect itself.
+ * The value of the need of touch effect means: \n
+ * true : A viewer is required to make the touch effect when a user clicks the widget, but it is just a recommendation.\n
+ * false : A viewer is not required to make the touch effect, the box will make the touch effect itself.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @param[in] widget_id appid of widget application
* @param[in] size_type Size type
* @param[out] need_of_touch_event the need of touch effect
- * @return 0 on success, otherwise a negative error value
- * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given.
- * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file.
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
+ * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
* @see widget_size_type_e
* @see widget_service_get_need_of_mouse_event()
* @see widget_service_get_need_of_frame()
*/
extern int widget_service_get_need_of_touch_effect(const char *widget_id, widget_size_type_e size_type, bool *need_of_touch_event);
+
/**
* @brief Gets the need of decoration frame for the given widget.
* @details This API gets the need of decoration frame for the given widget from database.\n
- * The value of the need of touch effect means... \n
- * true : the viewer should make decoration frame on outside of the widget.
- * false : no need to amke decoration frame.
+ * The value of the need of touch effect means: \n
+ * true : The viewer should make decoration frame outside of the widget.
+ * false : No need to make decoration frame.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @param[in] widget_id appid of widget application
* @param[in] size_type Size type
* @param[out] need_of_frame the need of decoration frame
- * @return 0 on success, otherwise a negative error value
- * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given.
- * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file.
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ * @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid parameter was given
+ * @retval #WIDGET_ERROR_IO_ERROR Some error occurs on opening DB file
* @see widget_service_get_need_of_mouse_event()
* @see widget_service_get_need_of_touch_effect()
*/
extern int widget_service_get_need_of_frame(const char *widget_id, widget_size_type_e size_type, bool *need_of_frame);
+
/**
* @brief Triggers the update event for given widget instance.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
- * @param[in] instance_id Set @c NULL if you don't know what the Id is. Then every instance of given pkgname will be triggered its update event
- * @param[in] b bundle data will be passed to the widget application via widget_update handler, default is @c NULL
- * @param[in] force 1 if you want to update your widget even if the provider is paused or 0. 0 is default
- * @return 0 on success, otherwise a negative error value
+ * @param[in] instance_id Set @c NULL if you don't know what the ID is. Then every instance of given pkgname will trigger its update event
+ * @param[in] b Bundle data will be passed to the widget application via widget_update handler, default is @c NULL
+ * @param[in] force 1 If you want to update your widget even if the provider is paused or 0. 0 is default
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
- * @retval #WIDGET_ERROR_CANCELED Provider is paused, so this update request is canceld.(ignored), if you want to make update forcely, use force=1
+ * @retval #WIDGET_ERROR_CANCELED Provider is paused, so this update request is canceled.(ignored), if you want to make update forcely, use force=1
* @retval #WIDGET_ERROR_OUT_OF_MEMORY Memory is not enough to make request
* @retval #WIDGET_ERROR_FAULT Failed to create a request packet
* @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
*/
extern int widget_service_trigger_update(const char *widget_id, const char *instance_id, bundle *b, int force);
+
/**
- * @brief Changes the update period of given widget instance.
+ * @brief Changes the update period of the given widget instance.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
- * @param[in] instance_id widget instance id
+ * @param[in] instance_id Widget instance ID
* @param[in] period New update period in sec
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_NONE Successfully changed(requested)
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_FAULT Failed to create a request packet
/**
- * @brief Callback function for getting result of widget_service_get_widget_list
+ * @brief Callback function for getting result of widget_service_get_widget_list.
* @since_tizen 2.3.1
* @param[in] pkgid package id
* @param[in] widget_id appid of widget application
* @param[in] is_prime will be sent as 1 if the widget is a default widget
- * @param[in] data user data
+ * @param[in] data user Data
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @return WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop
*/
typedef int (*widget_list_cb)(const char *pkgid, const char *widget_id, int is_prime, void *data);
+
/**
* @brief Gets a list of all widgets.
* @since_tizen 2.3.1
* @param[in] cb Callback function
- * @param[in] data user data for callback function
+ * @param[in] data user Data for callback function
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
*/
extern int widget_service_get_widget_list(widget_list_cb cb, void *data);
+
/**
- * @brief Gets the MAIN application Id of given widget package Id.
+ * @brief Gets the MAIN application ID of given widget package ID.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @remarks Result string should be freed by free()
+ * @remarks Result string should be freed by free().
* @param[in] widget_id appid of widget application
* @return char * type
- * @retval @c NULL If it fails to get main application Id (UI-APPID), get_last_result() will returns reason of failure.
+ * @retval @c NULL if it fails to get main application Id (UI-APPID), get_last_result() will returns reason of failure
* @retval appid Main application Id
* @see #get_last_result
*/
extern char *widget_service_get_main_app_id(const char *widget_id);
+
/**
- * @brief Callback function for getting result of widget_service_get_widget_list_by_pkgid
+ * @brief Callback function for getting result of widget_service_get_widget_list_by_pkgid.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
* @param[in] is_prime will be sent as 1 if the widget is a default widget
- * @param[in] data user data
+ * @param[in] data user Data
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @return WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop
*/
typedef int (*widget_list_by_pkgid_cb)(const char *widget_id, int is_prime, void *data);
+
/**
- * @brief Gets a list of widgets included in the given package id
+ * @brief Gets a list of widgets included in the given package ID.
* @since_tizen 2.3.1
- * @param[in] pkgid Package Id (Not the UI App Id)
+ * @param[in] pkgid Package ID (Not the UI App ID)
* @param[in] cb Callback function
* @param[in] data Callback data
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval int Count of widget packages
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
*/
extern int widget_service_get_widget_list_by_pkgid(const char *pkgid, widget_list_by_pkgid_cb cb, void *data);
+
/**
- * @brief Gets the id of a widget by the given id of package or UI app.
- * If there are two or more widgets in the package, this function returns the id of the primary widget.
+ * @brief Gets the ID of a widget by the given ID of package or UI app.
+ * If there are two or more widgets in the package, this function returns the ID of the primary widget.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @remarks Result string should be freed by free()
+ * @remarks Result string should be freed by free().
* @param[in] id Package Id or UI App Id
* @return char * type
- * @retval @c NULL Failed to get primary widget id, get_last_result() will returns reason of failure.
+ * @retval @c NULL Failed to get primary widget id, get_last_result() will returns reason of failure
* @retval widget_id Primary widget Id.
- * @pre Must be released returned string by manually.
+ * @pre Must release returned string manually.
* @see widget_service_package_id()
*/
extern char *widget_service_get_widget_id(const char *id);
+
/**
- * @brief Gets the appId of setup app which is specified by given widget Id's manifest.
- * @details
- * This setup app should be launched before adding the widget to get the content_info.\n
- * This function should be called before add a widget.\n
- * To determine the content information string.
+ * @brief Gets the appId of setup app which is specified by the given widget ID's manifest.
+ * @details This setup app should be launched before adding the widget to get the content_info.\n
+ * This function should be called before adding a widget.\n
+ * To determine the content information string.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @return char * type
* @retval @c NULL There is no setup application or error occurred, you can check it using get_last_result()
* @retval appid AppId if exists or @c NULL
- * @post Returned string must be free'd manually.
+ * @post Returned string must be freed manually.
* @see get_last_result()
*/
extern char *widget_service_get_app_id_of_setup_app(const char *widget_id);
+
/**
- * @brief Gets the package id of the given widget.
+ * @brief Gets the package ID of the given widget.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @param[in] widget_id appid of widget application
* @return char * type
* @retval appid String which is allocated in the heap
- * @retval @c NULL Invalid appid, get_last_result() will returns reason of failure if it fails.
+ * @retval @c NULL Invalid appid, get_last_result() will return reasons of failure if it fails
* @post Returned string must be free'd manually.
* @see widget_service_widget_id()
*/
extern char *widget_service_get_package_id(const char *widget_id);
+
/**
* @brief Gets the name of the given widget.
* @since_tizen 2.3.1
* @param[in] lang Locale(en-us, ko-kr, ...), if it is @c NULL, function will use the system locale automatically
* @return char * type
* @retval name If it fails to get name
- * @retval @c NULL Allocated heap address, get_last_result() will returns reason of failure if it fails.
- * @post Returned string must be free'd by manually.
+ * @retval @c NULL Allocated heap address, get_last_result() will return reasons of failure if it fails.
+ * @post Returned string must be freed manually.
* @see widget_service_i18n_icon()
* @see widget_service_preview()
*/
extern char *widget_service_get_name(const char *widget_id, const char *lang);
+
/**
* @brief Gets the preview image path of given size type.
* @details This function will return the preview image path.
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @remarks Result string should be freed by free()
+ * @remarks Result string should be freed by free().
* @param[in] widget_id appid of widget application
- * @param[in] size_type widget size type
+ * @param[in] size_type Widget size type
* @return char * type
* @retval path Preview image path
* @retval @c NULL There is no preview image file, get_last_result() will returns reason of failure if it fails.
- * @post Returned string must be free'd manually.
+ * @post Returned string must be freed manually.
* @see #widget_service_get_icon
* @see #widget_service_get_name
*/
extern char *widget_service_get_preview_image_path(const char *widget_id, widget_size_type_e size_type);
+
/**
* @brief Gets icon path of given widget package.
* @details The user should free the returned string with free().
* @since_tizen 2.3.1
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @remarks Result string should be freed by free()
- * @param[in] pkgid package id of widget application
+ * @remarks Result string should be freed by free().
+ * @param[in] pkgid Package ID of widget application
* @param[in] lang Locale(en-us, ko-kr, ...), if it is @c NULL, function will use the system locale automatically
* @return char * type
* @retval name Allocated heap address
- * @retval @c NULL Fails to get path of an icon, get_last_result() will returns reason of failure if it fails.
- * @post Returned string must be free'd manually.
+ * @retval @c NULL Fails to get path of an icon, get_last_result() will return reasons of failure if it fails
+ * @post Returned string must be freed manually.
* @see #widget_service_get_name
* @see #widget_service_get_preview_image_path
*/
extern char *widget_service_get_icon(const char *pkgid, const char *lang);
+
/**
- * @brief Gets the "nodisplay" value
+ * @brief Gets the "nodisplay" value.
* @since_tizen 2.3.1
* @privilege %http://tizen.org/privilege/widget.viewer
- * @param[in] widget_id Appid of widget application
+ * @param[in] widget_id appid of widget application
* @privlevel public
* @return The "nodisplay" value of given widget
* @retval 1 The box should not be listed by the widget list app
- * @retval 0 Box should be listed, get_last_result() will returns reason of failure if it fails
+ * @retval 0 Box should be listed, get_last_result() will return reasons of failure if it fails
* @pre Widget tag includes "nodisplay" attribute
*/
extern int widget_service_get_nodisplay(const char *widget_id);
+
/**
* @brief Gets the supported size list.
* @since_tizen 2.3.1
* @param[in,out] cnt Count of array w and h
* @param[out] w Width array
* @param[out] h Height array
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_NONE If succeed to get supported size list
* @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
*/
extern int widget_service_get_supported_sizes(const char *widget_id, int *cnt, int **w, int **h);
+
/**
- * @brief Gets the supported size list of given widget id.
+ * @brief Gets the supported size list of given widget ID.
* @since_tizen 2.3.1
* @param[in] widgetid appid of widget application
* @param[in] cnt Size of types array
* @param[out] types Array of types
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
* @retval #WIDGET_ERROR_NONE Successfully done
*/
extern int widget_service_get_supported_size_types(const char *widgetid, int *cnt, int **types);
+
/**
- * @brief Callback function for getting result of widget_service_get_widget_instance_list
+ * @brief Callback function for getting result of widget_service_get_widget_instance_list.
* @since_tizen 2.3.1
- * @param[in] widget_id widget app id
- * @param[in] widget_instance_id widget instance id
- * @param[in] data user data
+ * @param[in] widget_id Widget appid
+ * @param[in] widget_instance_id widget instance ID
+ * @param[in] data user Data
* @return WIDGET_ERROR_NONE to continue with the next iteration of the loop, other error values to break out of the loop
* @see #widget_service_get_widget_instance_list
*/
typedef int (*widget_instance_list_cb)(const char *widget_id, const char *instance_id, void *data);
+
/**
* @brief Gets widget instances of given widget_id.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
* @param[in] cb Callback function
- * @param[in] data user data for callback function
- * @return Negative error value on fail, otherwise count of instances
+ * @param[in] data user Data for callback function
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_NOT_EXIST Instance is not exist
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
*/
extern int widget_service_get_widget_instance_list(const char *widget_id, widget_instance_list_cb cb, void *data);
+
/**
- * @brief Enumerations for life cycle event of widgets
+ * @brief Enumeration for life cycle event of widgets.
* @since_tizen 2.3.1
* @see widget_lifecycle_event_cb
*/
WIDGET_LIFE_CYCLE_EVENT_MAX = 5
} widget_lifecycle_event_e;
+
/**
- * @brief Called when a widget is created or destroyed
+ * @brief Called when a widget is created or destroyed.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
- * @param[in] lifecycle_event type of event
- * @param[in] widget_instance_id widget instance id
+ * @param[in] lifecycle_event Type of event
+ * @param[in] widget_instance_id Widget instance ID
* @param[in] data user data
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @see #widget_service_set_lifecycle_event_cb
*/
typedef int (*widget_lifecycle_event_cb)(const char *widget_id, widget_lifecycle_event_e lifecycle_event, const char *widget_instance_id, void *data);
+
/**
- * @brief Registers event handler callback function for life-cycle events of widgets
+ * @brief Registers event handler callback function for life cycle events of widgets.
* @since_tizen 2.3.1
* @privlevel public
* @param[in] widget_id appid of widget application
* @param[in] cb Callback function
- * @param[in] data user data
- * @return 0 on success, otherwise a negative error value
+ * @param[in] data user Data
+ * @return @0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
* @see #widget_lifecycle_event_cb
*/
extern int widget_service_set_lifecycle_event_cb(const char *widget_id, widget_lifecycle_event_cb cb, void *data);
+
/**
- * @brief Unregisters event handler callback function for life-cycle events of widgets
+ * @brief Unregisters event handler callback function for life cycle events of widgets.
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
- * @param[out] user_data user callback data
- * @return 0 on success, otherwise a negative error value
+ * @param[out] user_data User callback data
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
* @retval #WIDGET_ERROR_PERMISSION_DENIED Permission denied
- * @retval #WIDGET_ERROR_NOT_EXIST Event handler callback function is not exist
+ * @retval #WIDGET_ERROR_NOT_EXIST Event handler callback function does not exist
* @see #widget_service_set_lifecycle_event_cb
*/
extern int widget_service_unset_lifecycle_event_cb(const char *widget_id, void **user_data);
+
/**
* @brief Gets content of the widget instance
* @since_tizen 2.3.1
* @param[in] widget_id appid of widget application
- * @param[in] widget_instance_id widget instance id
- * @param[out] b bundle(content) data of the given widget instance, it should be released by caller.
- * @return 0 on success, otherwise a negative error value
+ * @param[in] widget_instance_id Widget instance ID
+ * @param[out] b Bundle(content) data of the given widget instance, it should be released by caller.
+ * @return @c 0 on success,
+ * otherwise a negative error value
* @retval #WIDGET_ERROR_IO_ERROR Failed to access DB
* @retval #WIDGET_ERROR_INVALID_PARAMETER Invalid argument
- * @post caller should have to release the bundle
+ * @post Caller should have to release the bundle.
*/
extern int widget_service_get_content_of_widget_instance(const char *widget_id, const char *widget_instance_id, bundle **b);
+
+
/**
* @}
*/
projects / platform / core / appfw / widget-service.git / commitdiff