Managing widgets on the home screen

Home screen widgets are WRT widgets that are enabled for the home screen. They have two views, home screen view and a full screen view.

Mobile device users can manage widgets on the home screen, as follows:

Add a widget to the home screen.
Remove a widget from the home screen.
Suspend the home screen by sending from the foreground to the background.
Launch the home screen widget in full view.
Resume the home screen by sending it from the background to the foreground.

Home screen widget features

Mobile device users can access widgets from:

Home screen
Applications menu

The following table lists features of a widget enabled for the home screen and differences in the widget functionality in the home screen view and full screen view.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Widget feature	Home screen view	Full screen view
Users can interact with the widget	No	Yes
Widget appears in the open applications list	No The home screen is listed in the open applications list but individual home screen widgets are not	Yes
Users can exit the widget	No Users can remove widgets from the home screen	Yes However, the widget remains running in the background and is still displayed on the home screen, until users remove it
Users can uninstall the widget	Yes However, users must first remove the widget from the home screen	Yes However, users must first remove the widget from the home screen

Adding widgets to the home screen

Once mobile device users add widgets to the home screen, they are running. If users launche the widget (for example, from Applications ) the home screen widget is displayed in full screen view. A separate instance of the widget is not launched.

Widgets that you enable for the home screen are automatically added to the list of available content in home screen options in alphabetic order. The name that appears in the list is determined by the DisplayName key in the info.plist file.

Widgets that are currently displayed on the home screen are hidden from the content list. When users uninstall a widget, it is removed from the content list automatically.

The home screen informs the widget when users add a widget to the home screen. The widget responds by:

Launching the widget in the background.
Firing onload() and onshow() events.
Prompting the user for permissions.
Sending bitmap updates of the widget data to the home screen.

Removing widgets from the home screen

The home screen informs the widget when mobile device users remove a widget from the home screen. The widget shuts down.

Suspending the home screen

The home screen is suspended when it is sent to the background. This happens when mobile device users swap to another application, open a home screen widget in full view, and so forth. The widget responds by:

Suspending timers.
Suspending bitmap updates of the widget.
Firing an onhide() event.

Note: The widget does not need to do anything in response to the

onhide() event.

Opening home screen widgets in full screen view

The home screen informs the widget when a mobile device user selects a home screen widget to open in full screen view. Note that before informing the widget, the home screen suspends all other widgets on the home screen. The widget responds by:

Starting the JavaScript timers for the widget.
Firing onshow() and onresize() events for the widget.

Resuming the home screen

The home screen is resumed when the home screen is sent to the foreground. For example, when mobile device users swap back to the home screen from another application, users exit full view of a widget added to the home screen, and so forth. The widget responds by:

Starting JavaScript timers for all widgets added to the home screen.
Sending onshow() and onresize() events for all widgets added to the home screens.