Tizen Native API
Widget Application

Widget application API.

Required Header

#include <widget_app.h> #include <widget_app_efl.h>

Overview

The Widget Application 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 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

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.

Callback Description
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. 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.

Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.

widget_app_lifecycle.png
Widget Application States

Registering Callbacks for System Events

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 Application. The event for APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported in this module.

Registering callbacks for instance state change events

As for Tizen widget instance states, it is somewhat similer to Tizen application states.

Callback Description
widget_obj_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.
widget_obj_destroy_cb() Called before widget instance is destroyed. In this callback, you can finalize resources for this instance.
widget_obj_pause_cb() Called when the widget is invisible. The paused instance may be destroyed by framework
widget_obj_resume_cb() Called when the widget is visible. The callback function is called when the widget is visible.
widget_obj_resize_cb() Called before the widget size is changed. The callback function is called before the widget size is changed.
widget_obj_update_cb() Called when the event for updating widget is received. The callback function is called when the event for updating widget is received.

Please refer to the following state diagram to see the possible transitions and callbacks that are called while transition.

widget_obj_lifecycle.png
Widget Instance States

Functions

int widget_app_main (int argc, char **argv, widget_app_lifecycle_callback_s *callback, void *user_data)
 Runs the main loop of the application until widget_app_exit() is called.
int widget_app_exit (void)
 Exits the main loop of the application.
int widget_app_terminate_context (widget_context_h context)
 Finishes context for the widget instance.
int widget_app_foreach_context (widget_context_cb callback, void *data)
 Retrieves all widget contexts in this application.
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)
 Adds the system event handler.
int widget_app_remove_event_handler (app_event_handler_h event_handler)
 Removes registered event handler.
const char * widget_app_get_id (widget_context_h context)
 Gets a widget instance id.
widget_class_h widget_app_class_create (widget_instance_lifecycle_callback_s callback, void *user_data)
 Makes a class for widget instances.
int widget_app_context_set_tag (widget_context_h context, void *tag)
 Sets a tag in the context.
int widget_app_context_get_tag (widget_context_h context, void **tag)
 Gets the tag in the context.
int widget_app_context_set_content_info (widget_context_h context, bundle *content_info)
 Sets the content info to the widget.
int widget_app_context_set_title (widget_context_h context, const char *title)
 Sends the title to the widget.
int widget_app_get_elm_win (widget_context_h context, Evas_Object **win)
 Gets a evas object for the widget.

Typedefs

typedef enum
widget_app_destroy_type 
widget_app_destroy_type_e
 Destroys type of widget instance.
typedef struct _widget_class * widget_class_h
 The handle for widget class.
typedef struct _widget_context * widget_context_h
 The handle for widget context.
typedef int(* widget_instance_create_cb )(widget_context_h context, bundle *content, int w, int h, void *user_data)
 Called when the widget instance starts.
typedef int(* widget_instance_destroy_cb )(widget_context_h context, widget_app_destroy_type_e reason, bundle *content, void *user_data)
 Called before the widget instance is destroyed.
typedef int(* widget_instance_pause_cb )(widget_context_h context, void *user_data)
 Called when the widget is invisible.
typedef int(* widget_instance_resume_cb )(widget_context_h context, void *user_data)
 Called when the widget is visible.
typedef int(* widget_instance_resize_cb )(widget_context_h context, int w, int h, void *user_data)
 Called before the widget size is changed.
typedef int(* widget_instance_update_cb )(widget_context_h context, bundle *content, int force, void *user_data)
 Called when the event for updating widget is received.
typedef widget_class_h(* widget_app_create_cb )(void *user_data)
 Called when the application starts.
typedef void(* widget_app_terminate_cb )(void *user_data)
 Called when the application's main loop exits.
typedef bool(* widget_context_cb )(widget_context_h context, void *data)
 Called for each widget context.

Typedef Documentation

typedef widget_class_h(* widget_app_create_cb)(void *user_data)

Called when the application starts.

Since :
2.3.1

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.

Parameters:
[in]user_dataThe user data passed from the callback registration function
Returns:
The object of widget class
See also:
widget_app_main()
 static widget_class_h __widget_app_created(void *user_data)
 {
     widget_instance_lifecycle_callback_s callback = { .... };

     return widget_app_class_create(callback);
 }

Destroys type of widget instance.

Since :
2.3.1
typedef void(* widget_app_terminate_cb)(void *user_data)

Called when the application's main loop exits.

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 :
2.3.1
Parameters:
[in]user_dataThe user data passed from the callback registration function
See also:
widget_app_main()
typedef struct _widget_class* widget_class_h

The handle for widget class.

Since :
2.3.1
typedef bool(* widget_context_cb)(widget_context_h context, void *data)

Called for each widget context.

Since :
2.3.1

This function will be called in the function of widget_app_foreach_context repeatedly.

Parameters:
[in]contextThe context for widget instance
[in]dataThe data for caller
Returns:
true to continue with the next iteration of the loop, otherwise false to break out of the loop.
See also:
widget_app_foreach_context
typedef struct _widget_context* widget_context_h

The handle for widget context.

Since :
2.3.1
typedef int(* widget_instance_create_cb)(widget_context_h context, bundle *content, int w, int h, void *user_data)

Called when the widget instance starts.

Since :
2.3.1

The callback function is called after widget instance is created. In this callback, you can initialize resources for this instance.

Parameters:
[in]contextThe context of widget instance.
[in]contentThe data set for the previous status
[in]wThe pixel value for widget width
[in]hThe pixel value for widget height
[in]user_dataThe user data passed from widget_app_class_create function
Returns:
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)

Called before the widget instance is destroyed.

Since :
2.3.1

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_PERMANENT, It should store the current status by using incoming bundle.

Parameters:
[in]contextThe context of widget instance.
[in]reasonThe reason for destruction
[in,out]contentThe data set to save
[in]user_dataThe user data passed from widget_app_class_create function
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. The content will be overwritten after this callback returns with the 'content' parameter.
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
typedef int(* widget_instance_pause_cb)(widget_context_h context, void *user_data)

Called when the widget is invisible.

Since :
2.3.1

The callback function is called when the widget is invisible. The paused instance may be destroyed by framework

Parameters:
[in]contextThe context of widget instance.
[in]user_dataThe user data passed from widget_app_class_create function
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
typedef int(* widget_instance_resize_cb)(widget_context_h context, int w, int h, void *user_data)

Called before the widget size is changed.

Since :
2.3.1

The callback function is called before the widget size is changed.

Parameters:
[in]contextThe context of widget instance.
[in]wThe pixel value for widget width
[in]hThe pixel value for widget height
[in]user_dataThe user data passed from widget_app_class_create function
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
typedef int(* widget_instance_resume_cb)(widget_context_h context, void *user_data)

Called when the widget is visible.

Since :
2.3.1

The callback function is called when the widget is visible.

Parameters:
[in]contextThe context of widget instance.
[in]user_dataThe user data passed from widget_app_class_create function
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
typedef int(* widget_instance_update_cb)(widget_context_h context, bundle *content, int force, void *user_data)

Called when the event for updating widget is received.

Since :
2.3.1

The callback function is called when the event for updating widget is received.

Parameters:
[in]contextThe context of widget instance.
[in]contentThe data set for updating this widget. It will be provided by requester. Requester can use widget_service_trigger_update().
[in]forceAlthough the widget is paused, if it is TRUE, the widget can be updated.
[in]user_dataThe user data passed from widget_app_class_create function
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
See also:
widget_service_trigger_update

Enumeration Type Documentation

Destroys type of widget instance.

Since :
2.3.1
Enumerator:
WIDGET_APP_DESTROY_TYPE_PERMANENT 

User deleted this widget from the viewer

WIDGET_APP_DESTROY_TYPE_TEMPORARY 

Widget is deleted because of other reasons (e.g. widget process is terminated temporarily by the system)


Function Documentation

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 
)

Adds the system event handler.

Since :
2.3.1
Parameters:
[out]event_handlerThe event handler
[in]event_typeThe system event type. APP_EVENT_DEVICE_ORIENTATION_CHANGED is not supported
[in]callbackThe callback function
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfull
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_OUT_OF_MEMORYOut of memory
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
See also:
app_event_type_e
app_event_cb
watch_app_remove_event_handler

Makes a class for widget instances.

Since :
2.3.1
Parameters:
[in]callbackThe set of lifecycle callbacks
[in]user_dataThe user data to be passed to the callback functions
Returns:
The handle of class on success, otherwise NULL You can get the returned value using get_last_result()
Return values:
WIDGET_ERROR_NOT_SUPPORTEDNot supported
See also:
get_last_result
int widget_app_context_get_tag ( widget_context_h  context,
void **  tag 
)

Gets the tag in the context.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
[out]tagThe value to get
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_FAULTUnrecoverable error
int widget_app_context_set_content_info ( widget_context_h  context,
bundle content_info 
)

Sets the content info to the widget.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
[in]content_infoThe data set to save
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_OUT_OF_MEMORYOut of memory
WIDGET_ERROR_FAULTUnrecoverable error
WIDGET_ERROR_NONESuccessfully sent
int widget_app_context_set_tag ( widget_context_h  context,
void *  tag 
)

Sets a tag in the context.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
[in]tagThe value to save
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_FAULTUnrecoverable error
int widget_app_context_set_title ( widget_context_h  context,
const char *  title 
)

Sends the title to the widget.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
[in]titleWhen an accessibility mode is turned on, this string will be read.
Returns:
WIDGET_ERROR_NONE on success, otherwise an error code (see WIDGET_ERROR_XXX) on failure
Return values:
WIDGET_ERROR_INVALID_PARAMETERInvalid argument
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_OUT_OF_MEMORYOut of memory
WIDGET_ERROR_FAULTUnrecoverable error
WIDGET_ERROR_NONESuccessfully sent
int widget_app_exit ( void  )

Exits the main loop of the application.

The main loop of the application stops and widget_app_terminate_cb() is invoked.

Since :
2.3.1
Returns:
0 on success, otherwise a negative error value.
Return values:
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
See also:
widget_app_main
widget_app_terminate_cb
int widget_app_foreach_context ( widget_context_cb  callback,
void *  data 
)

Retrieves all widget contexts in this application.

Since :
2.3.1
Parameters:
[in]callbackThe iteration callback function
[in]dataThe data for the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfull
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_CANCELEDThe iteration is canceled
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
See also:
widget_app_foreach_context
int widget_app_get_elm_win ( widget_context_h  context,
Evas_Object **  win 
)

Gets a evas object for the widget.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
[out]winEvas object for window
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfull
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_FAULTFailed to make evas object
WIDGET_ERROR_NOT_SUPPORTEDNot supported
const char* widget_app_get_id ( widget_context_h  context)

Gets a widget instance id.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
Returns:
Widget ID on success, otherwise NULL You can get the returned value using get_last_result()
Return values:
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
Remarks:
You must not free returned Widget ID
See also:
get_last_result
int widget_app_main ( int  argc,
char **  argv,
widget_app_lifecycle_callback_s callback,
void *  user_data 
)

Runs the main loop of the application until widget_app_exit() is called.

Since :
2.3.1
Parameters:
[in]argcThe argument count
[in]argvThe argument vector
[in]callbackThe set of callback functions to handle application events
[in]user_dataThe user data to be passed to the callback functions
Returns:
0 on success, otherwise a negative error value.
Return values:
WIDGET_ERROR_NONESuccessful
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
See also:
widget_app_exit

Removes registered event handler.

Since :
2.3.1
Parameters:
[in]event_handlerThe event handler
Returns:
0 on success, otherwise a negative error value
Return values:
WIDGET_ERROR_NONESuccessfull
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error
See also:
watch_app_add_event_handler

Finishes context for the widget instance.

Since :
2.3.1
Parameters:
[in]contextThe context for widget instance
Returns:
0 on success, otherwise a negative error value.
Return values:
WIDGET_ERROR_NONESuccessfull
WIDGET_ERROR_INVALID_PARAMETERInvalid parameter
WIDGET_ERROR_NOT_SUPPORTEDNot supported
WIDGET_ERROR_FAULTUnrecoverable error