Widget

Widget API is a part of the Smart Extension APIs.

Some of our advanced accessories will support the Widget API. The Widget API enables the extension to display a live image on the accessory, sort of a preview of what the extension is about. The WIDGET_API_VERSION specifies if the accessory supports the Widget API and if so, which version that it supports.

Topics covered here:

1. How do extensions find out correct Widget image size
2. Update Widget image
3. Touch events

How do extensions find out correct Widget image size

Before an extension sends the Widget image to the Host Application, it has to figure out what size the image should be. This might vary between accessories as some have a larger display. In Widget API version 1 and 2, all widgets for a device should have the same size (specified in Registration.Device); also, an extension can have one widget for each host application.

Starting with Widget API version 3, a host application may support several different widget types and an extension can provide several different implementations for each of those types. The supported widget types are specified in Registration.Widget and each widget type is identified by the TYPE. The extension specifies its available widgets in the Registration.WidgetRegistration table, and the different widgets are identified by the KEY. The KEY is included in WIDGET_START_REFRESH_IMAGE_INTENT as EXTRA_KEY to specify which widget that was started. The WIDGET_START_REFRESH_IMAGE_INTENT also includes a EXTRA_INSTANCE_ID that is then used to refer to the started widget instance in all subsequent intents.

In Widget API version 3, the host application may position widgets based on a grid of cells. If the size of a widget does not match the size of the cells, the widget size will be rounded up to the nearest cell size.

Update Widget image

At certain occasions, the Host Application will request a Widget image from the extension, WIDGET_START_REFRESH_IMAGE_INTENT. E.g. when the user powers on the accessory, or when a new Widget extension is installed. When the extension receives this Intent, it must send back a Widget image to the Host Application, WIDGET_IMAGE_UPDATE_INTENT or WIDGET_PROCESS_LAYOUT_INTENT (in Widget API version 2 or later). The extension can continue to update its image until the intent WIDGET_STOP_REFRESH_IMAGE_INTENT is received. The extension can resume updating its image when WIDGET_START_REFRESH_IMAGE_INTENT has been received again.

Accessory state

Widgets may also visible when the accessory is in a low power mode and when disconnected ACCESSORY_STATE. The default behavior is that the same content is shown when the accessory is in low power mode POWERSAVE and nothing is displayed when the accessory is disconnected DISCONNECTED

If the extension wants to display content based on the accessory's state, it can provide EXTRA_ADDITIONAL_LAYOUTS with given EXTRA_ACCESSORY_STATE flag in the WIDGET_PROCESS_LAYOUT_INTENT intent. If the extension does not provide any content for a display mode, it will not be visible in that mode.

Touch events

In order to allow the user to interact with the Widget, the extension will get touch events that occur when your Widget is in focus on the accessory display. This way, the extension receives user feedback and can refresh the Widget image.

Touch events are sent to the extension through different intents depending on how the widget image is supplied. If the extension sends images in WIDGET_IMAGE_UPDATE_INTENT then touch events will be sent as WIDGET_ONTOUCH_INTENT intents. If the extension uses layouts to update the widget WIDGET_PROCESS_LAYOUT_INTENT, then touch events will be sent as WIDGET_OBJECT_CLICK_EVENT_INTENT intents.

As an example, one could mention a media player controller Widget. The initial Widget image shows a couple of buttons, play/pause, previous, next, etc. When a user presses somewhere on the Widget, the WIDGET_ONTOUCH_INTENT will be sent to the extension. Since the extension provided the initial image, it knows the exact layout/position of the buttons and can that way determine what button was pressed and take action. In this case, the action could be to start playing a song. The extension can also choose to update the Widget image so that it reflects the latest state, instead of the play button, it might a the pause button and the title of the playing song.