+ +

WidgetService: Providing Information about Installed Widgets

+ +

This tutorial demonstrates how you can retrieve installed widgets and additional information related to them.

+ +

The WidgetService API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

+ +

Warm-up

Become familiar with the Widget Service API basics by learning about:

Retrieving Widgets
Retrieve installed widgets.
Retrieving ID And Size Information
Retrieve information about primary id or size.
Retrieving Widget Name
Retrieve widget name.
Retrieving Widget Instances
Retrieve a list of widget's instances.
Retrieving Widget Variants
Retrieve widget variants.
Receiving Widget Change Notifications
Receive notifications about widget's life cycle.
Changing Update Period
Change the instance data update interval.
Sending And Getting Content
Manage content of the instance..

+ + + +

Learning how to retrieve installed widgets list is a basic Widget service skill:

Define a success handler implementing WidgetArraySuccessCallback() interface (in mobile and wearable applications). Optionally you can specify error handler too.

+var successCallback = function (widgets) {
+   console.log("There are " + widgets.length + " installed widgets");
+};
+
+var errorCallback = function (error) {
+   console.log("Error " + error.message);
+};

To get a list of all installed widgets use the getWidgets() method of the WidgetServiceManager interface (in mobile and wearable applications). If the optional parameter packageId is given, the only widgets belonging to the given package are returned.
```
+var packageId = "org.tizen.contacts";
+tizen.widgetservice.getWidgets(successCallback, errorCallback, packageId);
+
```
You can also get specific widget object by using the getWidget() method of the WidgetServiceManager interface (in mobile and wearable applications).
```
+var widget = tizen.widgetservice.getWidget("org.tizen.gallery.widget");
+
```

Retrieving ID And Size Information

+ +

Learning how to retrieve primary widget id or size makes using Widget service API easy and convenient:

To get primary widget id of given application or package id use the getPrimaryWidgetId() method of the WidgetServiceManager interface (in mobile and wearable applications).
```
+var widgetId = tizen.widgetservice.getPrimaryWidgetId("org.tizen.music-player");
+
```
To get size of the corresponding size type use the getSize() method of the PackageManager interface, specifying the size type.
```
+var widgetSize = tizen.widgetservice.getSize("4x4");
+
```

Retrieving Widget Name

+ +

Learning how to retrieve widget name:

Retrieve widget that name you would like to get.

+var widget = tizen.widgetservice.getWidget("org.tizen.gallery.widget");
+

To get widget name use the getName() method of the Widget interface. If the locale parameter is omitted then system locale one is used.
```
+var name = widget.getName("en-us");
+
```

Retrieving Widget Instances

+ +

Learning how to retrieve information about installed widget instances makes widget service API more useful:

Define a success handler implementing WidgetInstancesCallback() interface (in mobile and wearable applications). Optionally you can specify error handler too.

+var successCallback = function (instances) {
+   console.log("There are " + instances.length + " instances");
+};
+
+var errorCallback = function (error) {
+   console.log("Error " + error.message);
+};

To retrieve a list of all instances belonging to the widget, use the getInstances() method of the Widget interface (in mobile and wearable applications):
```
+widget.getInstances(successCallback, errorCallback);
+
```
To retrieve basic package information, use the getPackageInfo() method of the PackageManager interface, specifying the package ID. If no package ID is set, the method retrieves information of the application package calling the method.
```
var packageInfo = tizen.package.getPackageInfo("org.tizen.calculator");
```

+ + +

Retrieving Widget Variants

+ +

Learning how to retrieve variants representing all of the supported widget size types

Define a success handler implementing WidgetVariantsCallback() interface (in mobile and wearable applications). Optionally you can specify error handler too.

+var successCallback = function (variants) {
+   console.log("There are " + variants.length + " variants of the widget");
+};
+
+var errorCallback = function (error) {
+   console.log("Error " + error.message);
+};

Retrieve widget that variants you would like to obtain.

+var widget = tizen.widgetservice.getWidget("org.tizen.gallery.widget");
+

To get a list of all variants use the getVariants() method of the Widget interface (in mobile and wearable applications):
```
+widget.getVariants(successCallback, errorCallback);
+
```
You can also get specific variant by using the getVariant() method with one of the supported size type as a parameter.
```
+var variant = widget.getVariant("4x4");
+
```

Receiving Widget Change Notifications

+ +

Learning to receive notifications when the state of the widget has been changed. There are four states that can be noticed: CREATE, DESTROY, PAUSE and RESUME.

Define the event handler for state notifications using the WidgetChangeCallback listener interface (in mobile and wearable applications):

+var WidgetChangeCallback = function (instance, event) {
+   console.log("The instance " + instance + " has state " + event);
+};

Retrive widget object using the getWidget method of the WidgetServiceManager interface (in mobile and wearable applications)
```
+var widget = tizen.widgetservice.getWidget("org.tizen.music-player.widget");
+
```
Add the listener to use the defined event handler with the addStateChangeListener() method of the Widget interface (in mobile and wearable applications):
```
+var watchId = widget.addStateChangeListener(WidgetChangeCallback);
+
```
To stop receiving notifications for defined listener, use the removeStateChangeListener() method of the Widget interface with previously obtained listener id:
```
widget.removeStateChangeListener(watchId);
```

Changing Update Period

+ +

Learning how to change update interval for the widget instance:

First of all you have to retrive widget instance by getInstances() method.

+var instance;
+var successCallback = function (instances) {
+   instance = instances[0];
+};
+
+var widget = tizen.widgetservice.getWidget("org.tizen.gallery.widget");
+widget.getInstances(successCallback);
+

To change update interval use the changeUpdatePeriod() method of the WidgetInstance interface with new value in seconds.
+
```
+instance.changeUpdatePeriod(2);
+
```

Sending And Getting Content

+ +

Learning how to change update interval for the widget instance:

The first step is obtaining widget instance by getInstances() method.

+var instance;
+var successCallback = function (instances) {
+   instance = instances[0];
+};
+
+var widget = tizen.widgetservice.getWidget("org.tizen.gallery.widget");
+widget.getInstances(successCallback);
+

To change update interval use the changeUpdatePeriod() method of the WidgetInstance interface with new value in seconds.
+
```
+instance.changeUpdatePeriod(2);
+
```
To send data use the sendContent() method of the WidgetInstance interface. The second parameter decides if the instance will be updated even if the provider is paused.
+
```
+instance.sendContent(data, true);
+
```
You can also retrieve widget instance content. At the beginning define success handler implementing WidgetContentCallback() interface (in mobile and wearable applications). Optionally you can specify error handler too.
```
+var successCallback = function (object) {
+   console.log("Data successfully retrieved");
+};
+
+var errorCallback = function (error) {
+   console.log("Error " + error.message);
+};
```
Afterwards use getContent() method of the WidgetInstance interface.
+
```
+instance.getContent(successCallback, errorCallback);
+
```

+ + + + + +

Interface	Method
WidgetServiceManagerObject
WidgetServiceManager	+ +Widget getWidget (WidgetId widgetId) + void getWidgets (WidgetArraySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional PackageId? packageId) + +WidgetId getPrimaryWidgetId ((PackageId or ApplicationId) id) + +WidgetSize getSize (WidgetSizeType sizeType) +
Widget	+ DOMString getName (optional DOMString? locale) + void getInstances (WidgetInstancesCallback successCallback, optional ErrorCallback? errorCallback) + +WidgetVariant getVariant (WidgetSizeType sizeType) + void getVariants (WidgetVariantsCallback successCallback, optional ErrorCallback? errorCallback) + long addStateChangeListener (WidgetChangeCallback listener) + void removeStateChangeListener (long watchId) +
WidgetSize
WidgetVariant
WidgetInstance	+ void changeUpdatePeriod (double seconds) + void sendContent (Object data, boolean updateIfPaused) + void getContent (WidgetContentCallback successCallback, ErrorCallback errorCallback) +
WidgetArraySuccessCallback	void onsuccess (Widget[] widgets)
WidgetInstancesCallback	void onsuccess (WidgetInstance[] instances)
WidgetVariantsCallback	void onsuccess (WidgetVariant[] instances)
WidgetContentCallback	void onsuccess (Object data)
WidgetChangeCallback	void onchange (WidgetInstance instance, WidgetStateType event)

+Size type	+Size in pixels	+Supported profile
+1x1	+175x175	+This size type is not used. just defined for specifying a default cell size
+2x1	+354x175	+Mobile
+2x2	+354x354	+Mobile, Wearable
+4x1	+712x175	+Mobile
+4x2	+712x354	+Mobile
+4x3	+712x533	+Mobile
+4x4	+712x712	+Mobile
+4x5	+712x891	+Mobile
+4x6	+712x1070	+Mobile
+EASY_1x1	+224x215	+Mobile
+EASY_3x1	+680x215	+Mobile
+EASY_3x3	+680x653	+Mobile
+FULL	+720x1280	+Mobile

WidgetService

WidgetService: Providing Information about Installed Widgets

Warm-up

Retrieving Widgets

Retrieving ID And Size Information

Retrieving Widget Name

Retrieving Widget Instances

Retrieving Widget Variants

Receiving Widget Change Notifications

Changing Update Period

Sending And Getting Content

WidgetService API

Table of Contents

Summary of Interfaces and Methods

1. Type Definitions

1.1. WidgetId

1.2. WidgetInstanceId

1.3. WidgetSizeType

1.4. WidgetStateType

2. Interfaces

2.1. WidgetServiceManagerObject

2.2. WidgetServiceManager

Methods

2.3. Widget

Attributes

Methods

2.4. WidgetSize

Attributes

2.5. WidgetVariant

Attributes

2.6. WidgetInstance

Attributes

Methods

2.7. WidgetArraySuccessCallback

Methods

2.8. WidgetInstancesCallback

Methods

2.9. WidgetVariantsCallback

Methods

2.10. WidgetContentCallback

Methods

2.11. WidgetChangeCallback

Methods

3. Related Feature

4. Full WebIDL

Content

WidgetService API

Table of Contents

Summary of Interfaces and Methods

1. Type Definitions

1.1. WidgetId

1.2. WidgetInstanceId

1.3. WidgetSizeType

1.4. WidgetStateType

2. Interfaces

2.1. WidgetServiceManagerObject

2.2. WidgetServiceManager

Methods

2.3. Widget

Attributes

Methods

2.4. WidgetSize

Attributes

2.5. WidgetVariant

Attributes

2.6. WidgetInstance

Attributes

Methods

2.7. WidgetArraySuccessCallback

Methods

2.8. WidgetInstancesCallback

Methods

2.9. WidgetVariantsCallback

Methods

2.10. WidgetContentCallback

Methods

2.11. WidgetChangeCallback

Methods

3. Related Feature

4. Full WebIDL