Home Screen Publishing API: API description

Home Screen Publishing API is intended for any component or application wishing to cooperate with the home screen widget mechanism of the mobile device. It enables the publishing of content that may be used by the home screen widgets. Once a widget is published the mobile device user can add it to the home screen.

The content displayed in the widget solely relies on the content available in widget items, published by this API. It is possible to publish data by means of a predefined widget templates. Published data may be image and/or text. Data may be published, updated, and deleted. The access control list is set automatically and it is responsible for allowing modification only from the application that has originally published the content. The picture below depicts a home screen with five widgets.

Home Screen Publishing API also allows to setup a notification mechanism on the written widget, thus allowing the client application to be informed about a certain range of events that refer to the data. The events of which the client application will be informed are:

• for the widget itself:
  • activate
    • the widget is added to the home screen
  • deactivate
    • the widget is removed from the home screen
  • suspend
    • the home screen goes to the background
    • the backlight turns off
  • resume
    • the home screen comes to the foreground
    • the backlight turns on
• for each widget item:
  • select

The diagram below describes the states of Home Screen Publishing API.

Capabilities

No capabilities are required.

Use case

The use case for the Home Screen Publishing API demonstrates how to make the application such that it can cooperate with the home screen mechanism. The use case's steps show how to add a new widget, how to add or remove content from it, and how to manage the content based on the received information about the occurred events.

API class structure

HsWidget class is used for defining a home screen widget (a widget is identified by its template name, widget name, and unique identifier.) The class provides with adding a new widget item to the widget if it wasn't created earlier and setting a new value to the existing widget item.

HsWidgetPublisher class is used for allowing the access to the Home Screen Publishing API. The class provides with creation, update and deletion of widgets, as well as reception of information for occurring widget and widget item events. HsWidgetPublisher is the constructor of the Home Screen Publishing API and it creates an instance of the publisher, which is used to manage widgets and widget items.

IHsDataObserver class is used for defining the actions that may take place for a home screen widget and widget item. The client must implement it to be able to get information about occurring actions from the Home Screen Publishing API.

HsException class is used for encapsulating error information thrown in exceptions by the Home Screen Publishing API.