Widget modes: docked, widget and more

Abstract

On some platforms the Opera Widgets runtime supports more than one mode for the widget to run in, for instance a mobile phone may support both to show widgets one at a time in full screen mode and to show multiple widgets with each widget displayed in a separate slot on the screen.

The widget runtime will tell the widget what mode it should run in. The runtime has a fallback solution in case the widget does not support the requested mode.

The currently defined modes are: Widget, docked, application and fullscreen.

Note: The spec for Widget modes is not yet finalized.

1. Widget modes defined
   1. Widget mode
   2. Application mode
   3. Fullscreen mode
2. Using CSS to adapt to the current widget mode: The -o-widget-mode media query
3. Using JavaScript to adapt to the current widget mode: WidgetModeChangeEvent
4. Resources

Widget modes defined

The Opera Widget runtime is available on many platforms, including mobile phones, game consoles, media players, set top boxes and desktop computers. These platforms have different characteristics and use cases. The widget runtime has been integrated into the device to best support the devices’ characteristics. Widgets may be requested by the runtime to display in one of four different modes:

• Widget mode
• Docked mode
• Application mode
• Fullscreen mode

The default mode of the widget is determined by the defaultmode attribute of the widget element in the widget’s config.xml file. The Widget runtime may request the widget to switch between the modes, e.g from docked to application and then to fullscreen mode. Docked mode may for instance be used to show widgets on the phone idle screen.

Widget mode

The widget mode is the default mode and how widgets traditionally have been displayed. Each widget is rendered in it’s own window, separate from the browser and without any chrome. The size of the widget is determined by config.xml. The author needs to supply mechanisms for resizing and moving the widget if this is desired. This is the default mode if nothing else is specified in the widget’s config.xml file.

Application mode

Like the widget mode, widgets in application mode are rendered in their own window. Unlike the widget mode, these now have chrome. This means widgets in this mode look more like native applications. The widget can be moved and resized as a normal window. You can set application mode to be the default mode by setting the widgetmode attribute of the widget element to ‘application’ in the widget’s config.xml file.

Fullscreen mode

Fullscreen mode (see Figure 1) looks like application mode except that the widget is rendered as an otherwise maximized native application. You can set fullscreen mode to be the default mode by setting the widgetmode attribute of the widget element to ‘fullscreen’ in the widget’s config.xml file.

Figure 1: A Widget in fulllscreen mode.

Docked mode

The docked mode, also known as micro widget mode, is a minimized version of the widget, typically docked into a panel. It can show summary information, a status icon or similar. An example is a small news ticker where news items move across a small horizontal bar, or a traffic light to signify the health of a monitored device. A widget is not dockable by default - in order to make it dockable, you need to set the dockable attribute of the widget element to ‘dockable’ or ‘true’ in the widget’s config.xml file. Figure 2 shows some exaples of widgets in docked mode.

Figure 2: Widgets in docked mode.

Using CSS to adapt to the current widget mode: The -o-widget-mode media query

You may style a widget differently for each mode by using a new media query property called -o-widget-mode. Possible values for the property are ‘widget’, ‘application’, ‘fullscreen’ and ‘docked’. Use it as part of a media query like this:

@media all and (-o-widget-mode:application {
  /* We don't need to display our own user chrome controls, since
     real chrome is provided */
  .fakeChrome { display: none; }
}

By doing a query for the -o-widget-mode property without a value, you can determine if the platform supports widget modes at all:

@media all and (-o-widget-mode) {
  div.friendlyMessage {
    content: "I will be displayed if I am a modern widget";
  }
}

Using Javascript to adapt to the current widget mode: WidgetModeChangeEvent

When the widget mode changes, a WidgetModeChangeEvent is fired on the widget object. By catching these events, you can programatically adapt the widget to it’s new state. An example is changing the DOM of the widget when it goes in and out of docked mode.

widget.addEventListener( 'widgetmodechange', function (e)
{
    //Change the DOM to show minimal status information
}, false );

When the widget mode changes, the available display area may also change. If so, a ResolutionEvent will be fired to provide the new width and height as properties of the event object.

widget.addEventListener( 'resolution', function (e)
{
    //Resize and restyle the widget
}, false );

Resources

• Opera Widgets Specification 1.0, third edition