} widget_type_e;
/**
- * @brief Enumeration for widget event type.
- * @details These events will be sent from the provider.
- * @since_tizen 2.4
- */
-typedef enum widget_event_type { /**< widget_event_handler_set Event list */
- WIDGET_EVENT_WIDGET_UPDATED, /**< Contents of the given widget is updated */
- WIDGET_EVENT_WIDGET_EXTRA_UPDATED,
- WIDGET_EVENT_GBAR_UPDATED, /**< Contents of the given pd is updated */
- WIDGET_EVENT_GBAR_EXTRA_UPDATED,
-
- WIDGET_EVENT_CREATED, /**< A new widget is created */
- WIDGET_EVENT_DELETED, /**< A widget is deleted */
-
- WIDGET_EVENT_GROUP_CHANGED, /**< Group (Cluster/Sub-cluster) information is changed */
- WIDGET_EVENT_PINUP_CHANGED, /**< PINUP status is changed */
- WIDGET_EVENT_PERIOD_CHANGED, /**< Update period is changed */
-
- WIDGET_EVENT_WIDGET_SIZE_CHANGED, /**< widget size is changed */
- WIDGET_EVENT_GBAR_SIZE_CHANGED, /**< Glance Bar size is changed */
-
- WIDGET_EVENT_GBAR_CREATED, /**< If a Glance Bar is created even if you didn't call the widget_create_glance_bar API */
- WIDGET_EVENT_GBAR_DESTROYED, /**< If a Glance Bar is destroyed even if you didn't call the widget_destroy_glance_bar API */
-
- WIDGET_EVENT_HOLD_SCROLL, /**< If the screen should be freezed */
- WIDGET_EVENT_RELEASE_SCROLL, /**< If the screen can be scrolled */
-
- WIDGET_EVENT_WIDGET_UPDATE_BEGIN, /**< widget content update is started */
- WIDGET_EVENT_WIDGET_UPDATE_END, /**< widget content update is finished */
-
- WIDGET_EVENT_GBAR_UPDATE_BEGIN, /**< Glance Bar content update is started */
- WIDGET_EVENT_GBAR_UPDATE_END, /**< Glance Bar content update is finished */
-
- WIDGET_EVENT_UPDATE_MODE_CHANGED, /**< widget Update mode is changed */
-
- WIDGET_EVENT_REQUEST_CLOSE_GBAR, /**< widget requests to close the Glance Bar */
-
- WIDGET_EVENT_EXTRA_INFO_UPDATED, /**< Extra information is updated */
-
- WIDGET_EVENT_WIDGET_EXTRA_BUFFER_CREATED, /**< WIDGET Extra Buffer created event */
- WIDGET_EVENT_GBAR_EXTRA_BUFFER_CREATED, /**< GBAR Extra Buffer created event */
-
- WIDGET_EVENT_WIDGET_EXTRA_BUFFER_DESTROYED, /**< WIDGET Extra Buffer destroyed event */
- WIDGET_EVENT_GBAR_EXTRA_BUFFER_DESTROYED, /**< WIDGET Extra Buffer destroyed event */
-
- WIDGET_EVENT_IGNORED = 0xFF /**< Request is ignored */
-} widget_event_type_e;
-
-/**
* @brief Enumeration for widget option types.
* @since_tizen 2.4
*/
double y; /**< Y Coordinates that the event occurred */
widget_access_info_type_e type; /**< Accessibility event type */
int info; /**< Extra information for this event */
-} *widget_access_event_info_t;
+} *widget_access_event_info_s;
/**
* @internal
int y; /**< Coordinates Y of Left-Top corner */
int w; /**< Damage'd Width */
int h; /**< Damage'd Height */
-} widget_damage_region_t;
+} widget_damage_region_s;
/**
* @internal
typedef struct widget_mouse_event_info {
double x; /**< X coordinates of Mouse Event */
double y; /**< Y coordinates of Mouse Event */
-} *widget_mouse_event_info_t;
+} *widget_mouse_event_info_s;
/**
* @internal
*/
typedef struct widget_key_event_info {
unsigned int keycode; /**< Key code */
-} *widget_key_event_info_t;
+} *widget_key_event_info_s;
/**
* @internal
double ex;
double ey;
} geometry;
-} *widget_text_event_t;
+} *widget_text_event_s;
/**
* @internal
int (*update_access)(widget_h handle, const char *id, const char *part, const char *text, const char *option); /**< Update access information */
int (*operate_access)(widget_h handle, const char *id, const char *part, const char *operation, const char *option); /**< Update access operation */
int (*update_color)(widget_h handle, const char *id, const char *part, const char *data); /**< Update color */
-} *widget_script_operator_t;
+} *widget_script_operator_s;
/**
* @internal
* 23x23=680x653, #WIDGET_SIZE_TYPE_EASY_3x3
*
* Special widget
- * 0x0=720x1280, #WIDGET_SIZE_TYPE_0x0
+ * 0x0=720x1280, #WIDGET_SIZE_TYPE_FULL
* @since_tizen 2.3
* @remarks
* This is an ASYNCHRONOUS API.
* 23x23=680x653, WIDGET_SIZE_TYPE_EASY_3x3
*
* Special mode widget size
- * 0x0=720x1280, WIDGET_SIZE_TYPE_0x0
+ * 0x0=720x1280, WIDGET_SIZE_TYPE_FULL
* @since_tizen 2.4
* @privlevel public
* @privilege %http://tizen.org/privilege/widget.viewer
* @see widget_feed_access_event()
* @see widget_feed_key_event()
*/
-extern int widget_viewer_feed_mouse_event(widget_h handle, widget_mouse_event_type_e type, widget_mouse_event_info_t info);
+extern int widget_viewer_feed_mouse_event(widget_h handle, widget_mouse_event_type_e type, widget_mouse_event_info_s info);
/**
* @internal
* @see widget_feed_mouse_event()
* @see widget_feed_key_event()
*/
-extern int widget_viewer_feed_access_event(widget_h handle, widget_access_event_type_e type, widget_access_event_info_t info, widget_ret_cb cb, void *data);
+extern int widget_viewer_feed_access_event(widget_h handle, widget_access_event_type_e type, widget_access_event_info_s info, widget_ret_cb cb, void *data);
/**
* @internal
* @see widget_feed_mouse_event()
* @see widget_feed_access_event()
*/
-extern int widget_viewer_feed_key_event(widget_h handle, widget_key_event_type_e type, widget_key_event_info_t info, widget_ret_cb cb, void *data);
+extern int widget_viewer_feed_key_event(widget_h handle, widget_key_event_type_e type, widget_key_event_info_s info, widget_ret_cb cb, void *data);
/**
* @internal
* @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid argument
* @see widget_set_gbar_text_handler()
*/
-extern int widget_viewer_set_text_handler(widget_h handle, int gbar, widget_script_operator_t ops);
+extern int widget_viewer_set_text_handler(widget_h handle, int gbar, widget_script_operator_s ops);
/**
* @internal
* @retval #WIDGET_STATUS_ERROR_NONE Successfully emitted
* @see widget_ret_cb
*/
-extern int widget_viewer_emit_text_signal(widget_h handle, widget_text_event_t event_info, widget_ret_cb cb, void *data);
+extern int widget_viewer_emit_text_signal(widget_h handle, widget_text_event_s event_info, widget_ret_cb cb, void *data);
/**
* @internal
* @retval #WIDGET_STATUS_ERROR_NONE if success
* @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid handle
*/
-extern int widget_viewer_get_damaged_region(widget_h handle, int gbar, const widget_damage_region_t *region);
+extern int widget_viewer_get_damaged_region(widget_h handle, int gbar, const widget_damage_region_s *region);
/**
* @internal
#ifndef __WIDGET_VIEWER_EVAS_H
#define __WIDGET_VIEWER_EVAS_H
+#include "widget_service.h"
+
#ifdef __cplusplus
extern "C" {
#endif
#define WIDGET_VIEWER_EVAS_DEFAULT_PERIOD -1.0f /**< Default Update Period */
+
+/**
+ * @sine_tizen 2.4
+ * @brief Event names for smart callback of widget events. You can listen some events from widget by calling evas_object_smart_callback_add.
+ * @see #widget_evas_event_info_s
+ */
#define WIDGET_SMART_SIGNAL_WIDGET_CREATE_ABORTED "widget,create,aborted" /**< widget creation is aborted */
#define WIDGET_SMART_SIGNAL_WIDGET_CREATED "widget,created" /**< widget is created */
#define WIDGET_SMART_SIGNAL_WIDGET_RESIZE_ABORTED "widget,resize,aborted" /**< Resizing widget is aborted */
#define WIDGET_SMART_SIGNAL_WIDGET_DELETED "widget,deleted" /**< widget is deleted */
#define WIDGET_SMART_SIGNAL_PERIOD_CHANGED "widget,period,changed" /**< Period is changed */
+/**
+ * @sine_tizen 2.4
+ * @brief Data structure for smart callback user parameter
+ */
+typedef struct widget_evas_event_info {
+ const char *pkgname; /**< widget application id */
+ widget_event_type_e event; /**< event type for detail event information - WIDGET_EVENT_XXX, refer the widget_serivce.h */
+ int error; /**< Error type - WIDGET_ERROR_XXX, refer the widget_errno.h */
+} widget_evas_event_info_s;
+
+/**
+ * @sine_tizen 2.4
+ * @brief Data structure for smart callback user parameter
+ */
typedef enum widget_evas_raw_event_type {
WIDGET_VIEWER_EVAS_RAW_DELETE = 0x00,
WIDGET_VIEWER_EVAS_RAW_CREATE = 0x02,
WIDGET_VIEWER_EVAS_UNKNOWN = 0xFFFF
} widget_evas_conf_e;
-/**
- * \brief
- * Data structure for smart callback user parameter
- */
-typedef struct widget_evas_event_info {
- const char *pkgname; /**< widget application Id */
- int event; /**< Event type - WIDGET_EVENT_XXX, refer the widget_viewer.h */
- int error; /**< Error type - WIDGET_STATUS_XXX, refer the widget_viewer.h */
-} widget_evas_event_info_t;
-
typedef struct widget_evas_raw_event_info {
const char *pkgname;
enum widget_evas_raw_event_type type;
int error;
Evas_Object *widget;
-} widget_evas_raw_event_info_t;
+} widget_evas_raw_event_info_s;
/**
- * @brief Initialize the widget system
+ * @brief Initializes the widget system
* @since_tizen 2.4
* @param[in] win Window object
* @param[in] force_to_buffer if you want use the naive buffer directly (instead of resource id), use 1 or 0.
* @return int
* @retval
- * @see widget_viewer_evas_fini()
+ * @see #widget_viewer_evas_fini
*/
extern int widget_viewer_evas_init(Evas_Object *win, int force_to_buffer);
/**
- * @brief Finalize the widget system
+ * @brief Finalizes the widget system
* @since_tizen 2.4
* @return int
* @retval
- * @see widget_viewer_evas_init()
+ * @see #widget_viewer_evas_init
*/
extern int widget_viewer_evas_fini(void);
/**
- * @brief Create a new widget object
+ * @brief Creates a new widget object
* @since_tizen 2.4
- * @param[in] parent
- * @param[in] widget_id
- * @param[in] content_info
- * @param[in] cluster
- * @param[in] category
- * @param[in] period update period
+ * @param[in] parent Evas Object of parent
+ * @param[in] widget_id widget id
+ * @param[in] content_info Contents that will be given to the widget instance
+ * @param[in] cluster Main group
+ * @param[in] category Sub group
+ * @param[in] period Update period (@c WIDGET_DEFAULT_PERIOD can be used for this; this argument will be used to specify the period of updating contents of a widget)
* @return Evas_Object*
- * @retval NULL if it fails to create a new widget object
+ * @retval NULL if it fails to create a new widget object and you can get the reason of failure using widget_last_status()
+ * @see #widget_service_get_widget_id
+ * @see #widget_service_get_content_string
+ * @see #widget_service_get_category
*/
extern Evas_Object *widget_viewer_evas_add_widget(Evas_Object *parent, const char *widget_id, const char *content_info, const char *cluster, const char *category, double period);
+/**
+ * @brief Subscribes an event for widgets only in a given cluster and sub-cluster.
+ * @details If you wrote a view-only client,
+ * you can receive the event of specific widgets which belong to a given cluster/category.
+ * But you cannot modify their attributes (such as size, ...).
+ * @since_tizen 2.4
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] cluster Cluster ("*" can be used for subscribe all cluster's widgets event; If you use the "*", value in the category will be ignored)
+ * @param[in] category Category ("*" can be used for subscribe widgets events of all category(sub-cluster) in a given "cluster")
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT Unrecoverable error occurred
+ * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
+ * @see widget_viewer_evas_unsubscribe_group()
+ */
extern int widget_viewer_evas_subscribe_group(const char *cluster, const char *sub_cluster);
+
+
+/**
+ * @brief Unsubscribes an event for the widgets, but you will receive already added widgets events.
+ * @since_tizen 2.3
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] cluster Cluster("*" can be used for subscribe all cluster's widgets event; If you use the "*", value in the category will be ignored)
+ * @param[in] category Category ("*" can be used for subscribe all sub-cluster's widgets event in a given "cluster")
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT Unrecoverable error occurred
+ * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
+ * @see widget_subscribe_group()
+ */
extern int widget_viewer_evas_unsubscribe_group(const char *cluster, const char *sub_cluster);
+/**
+ * @brief Subscribes events of widgets which is categorized by given "category" string.
+ * "category" is written in the XML file of each widget manifest file.
+ * After subscribe the category, the master will send created event for all created widgets,
+ * Also it will notify client when a new widget is created.
+ * @since_tizen 2.4
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] category Category name
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT Unrecoverable error occurred
+ * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
+ * @see widget_viewer_evas_unsubscribe_category()
+ */
extern int widget_viewer_evas_subscribe_category(const char *category);
-extern int widget_viewer_evas_unsubscribe_category(const char *category);
/**
- * @brief if a viewer is resumed, use this function to notify it to the providers.
+ * @brief Unsubscribes events of widgets.
* @since_tizen 2.4
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] category Category name
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT Unrecoverable error occurred
+ * @retval #WIDGET_STATUS_ERROR_NONE Successfully requested
+ * @see widget_viewer_evas_subscribe_category()
+ */
+extern int widget_viewer_evas_unsubscribe_category(const char *category);
+
+/**
+ * @brief Notifies the status of a client ("it is paused") to the provider.
* @details if you call this, all providers will gets resumed event.
- * @return int
- * @see widget_viewer_evas_paused()
+ * @since_tizen 2.4
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT if it failed to send state (paused) info
+ * @see widget_viewer_evas_notify_paused_status_of_viewer()
*/
extern int widget_viewer_evas_notify_resumed_status_of_viewer(void);
/**
- * @brief If a viewer is paused, use this function to notify it to the providers
- * @since_tizen 2.4
+ * @brief Notifies the status of client ("it is resumed") to the provider.
* @detail if you call this, all providers will gets paused event.
- * @return int
+ * @since_tizen 2.4
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT if it failed to send state (resumed) info
+ * @see widget_viewer_evas_notify_resumed_status_of_viewer()
*/
extern int widget_viewer_evas_notify_paused_status_of_viewer(void);
/**
- * @brief Change the state of each widget. if you want made a box should be paused, call this.
+ * @brief Changes the state of given widget. If you want to make a widget paused, call this function.
* @since_tizen 2.4
- * @param[in] widget widget object
- * @return int
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] widget widget Evas object
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT if it failed to send state (resumed) info
*/
extern int widget_viewer_evas_pause_widget(Evas_Object *widget);
/**
- * @brief Change the state of each widget. If you want made a box should be resumed, call this.
+ * @brief Changes the state of given widget. If you want to make a widget resumed, call this function.
* @since_tizen 2.4
- * @param[in] widget widget object
- * @return int
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/widget.viewer
+ * @param[in] widget widget Evas object
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_FAULT if it failed to send state (resumed) info
*/
extern int widget_viewer_evas_resume_widget(Evas_Object *widget);
-
-
/**
- * @brief Change the configurable values of widget system
+ * @brief Changes the configurable values of widget system
* @since_tizen 2.4
* @param[in] type Configuration item
* @param[in] value Its value
- * @return int
+ * @return #WIDGET_STATUS_ERROR_NONE on success,
+ * otherwise an error code (see #WIDGET_STATUS_ERROR_XXX) on failure
+ * @retval #WIDGET_STATUS_ERROR_INVALID_PARAMETER Invalid option
+ * @see #widget_evas_conf
*/
extern int widget_viewer_evas_set_option(enum widget_evas_conf type, int value);
/**
- * @brief Content string of widget
+ * @brief Gets content string of widget
+ * @details This string can be used for creating contents of widget again after reboot a device or recovered from crash(abnormal status)
* @since_tizen 2.4
- * @details This string should be used for creating widget again after reboot device or recovered from crash(abnormal status)
* @param[in] widget widget object
- * @return const char * String of content
+ * @return content string to be recognize content of the widget
* @retval NULL if there is no specific content string.
*/
extern const char *widget_viewer_evas_get_content_string(Evas_Object *widget);
/**
- * @brief Summarized string of widget content.
+ * @brief Gets summarized string of the widget content for accessibility.
+ * @details If the accessibility feature is turned on, a viewer can use this text to describe the widget.
* @since_tizen 2.4
- * @details If the accessibility feature is turned on, the homescreen can read this text to describe the widget.
* @param[in] widget widget object
- * @return const char * Text should be read
- * @retval NULL if there is no summarized text for content of given widget
+ * @return title string to be used for summarizing the widget
+ * @retval NULL if there is no summarized text for content of given widget.
*/
extern const char *widget_viewer_evas_get_title_string(Evas_Object *widget);
/**
- * @brief Get the widget Id
+ * @brief Gets the id of the widget
* @since_tizen 2.4
* @param[in] widget widget object
* @return const char * widget Id
extern const char *widget_viewer_evas_get_widget_id(Evas_Object *widget);
/**
- * @brief Current period of updates
+ * @brief Gets the update period of the widget.
* @since_tizen 2.4
* @param[in] widget widget object
- * @return double
+ * @return period the update period of the widget.
* @retval Update period
*/
extern double widget_viewer_evas_get_period(Evas_Object *widget);
/**
- * @brief Cancelate click event procedure.
+ * @brief Cancels click event procedure.
+ * @details If you call this function after feed the mouse_down(or mouse_set) event, the widget will get ON_HOLD events.\n
+ * If a widget gets ON_HOLD event, it will not do anything even if you feed mouse_up(or mouse_unset) event.\n
* @since_tizen 2.4
- * @details If you call this after feed the mouse_down(or mouse_set) event, the box will get ON_HOLD events.\n
- * If a box gets ON_HOLD event, it will not do anything even if you feed mouse_up(or mouse_unset) event.\n
* @param[in] widget widget object
* @return void
*/
/**
* @brief This function should be called right after create the widget object. before resizing it.
* @since_tizen 2.4
- * @param[in] widget
+ * @param[in] widget widget object
* @return void
*/
extern void widget_viewer_evas_disable_preview(Evas_Object *widget);
/**
* @brief While loading a box, hide the help text
* @since_tizen 2.4
- * @param[in] widget
+ * @param[in] widget widget object
* @return void
*/
extern void widget_viewer_evas_disable_overlay_text(Evas_Object *widget);
/**
* @brief Do not display the overlay layer while loading a new box.
- * @since_tizen 2.4
* @details if you disable it, there is no preview & help text while creating a widget object
+ * @since_tizen 2.4
+ * @param[in] widget widget object
* @return void
*/
extern void widget_viewer_evas_disable_loading(Evas_Object *widget);
/**
- * @brief Feeds the mouse_up event forcibly.
- * @since_tizen 2.4
+ * @brief Feeds the mouse_up event to the provider.
* @details This is very similar with widget_viewer_evas_cancel_click(), but this will sends mouse_up event explicitly.\n
* Also feed the ON_HOLD event before feeds mouse_up event.
- * @param[in] widget widget
+ * @since_tizen 2.4
+ * @param[in] widget widget object
* @return int
*/
extern int widget_viewer_evas_feed_mouse_up_event(Evas_Object *widget);
/**
* @brief Activate
* @since_tizen 2.4
- * @param[in] widget
+ * @param[in] widget widget object
+ * @return void
*/
-extern void widget_viewer_evas_activate(Evas_Object *widget);
+extern void widget_viewer_evas_activate_faulted_widget(Evas_Object *widget);
/**
- * @brief
+ * @brief Check whether the widget is faulted.
* @since_tizen 2.4
* @param[in] widget
*/
extern int widget_viewer_evas_is_faulted(Evas_Object *widget);
/**
- * @brief
+ * @brief Unregister a callback function for subscribing raw event.
* @since_tizen 2.4
* @param[in] type
* @param[in] cb
extern int widget_viewer_evas_unset_raw_event_callback(enum widget_evas_raw_event_type type, void (*cb)(struct widget_evas_raw_event_info *info, void *data), void *data);
/**
- * @brief
+ * @brief Register a callback function for subscribing raw event.
* @since_tizen 2.4
* @param[in] type
* @param[in] cb
extern int widget_viewer_evas_freeze_visibility(Evas_Object *widget, int status);
/**
- * @brief
+ * @brief If you want to let the visibility change automatically again, call this function.
* @since_tizen 2.4
* @param[in] widget
* @return int
*/
extern int widget_viewer_evas_get_freeze_visibility(Evas_Object *widget);
-
-
/**
* @brief Validate the object, whether it is a widget object or not
* @since_tizen 2.4
projects / platform / core / appfw / widget-viewer.git / commitdiff