# 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:

1. Launching the widget in the background.

2. Firing `onload()` and `onshow()` events.

3. Prompting the user for permissions.

4. 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:

1. Suspending timers.

2. Suspending bitmap updates of the widget.

3. 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:

1. Starting the JavaScript timers for the widget.

2. 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:

1. Starting JavaScript timers for all widgets added to the home screen.

2. Sending `onshow()` and `onresize()` events for all widgets added to the home screens.