Opera Widgets - core DOM reference

By Opera Software

Introduction

This document describes the widget object and extensions to the window object that are available to a widget through JavaScript. This API allows you to communicate with the underlying widget runtime. The runtime offers some services such as showing and hiding the widget, storing preferences for the widget and getting information about the running widget.

The methods and properties in this API, the widget object and the extensions to the standard window object are only available if the code is running inside a widget, i.e. if it is inside a package or directory containing a config.xml and opened as a widget in the Opera browser. Unless otherwise stated, all objects are available in the JavaScript global scope.

Widget identity and origin

When you install a widget, the browser will give it a unique id, which you can use to refer to it later. This is exposed in the widget.identifier property and can be used with among other things the widget URL protocol.

Furthermore, the URL where the widget was downloaded from is exposed on widget.originURL. One use of this is to supply users with a link to find out more information about the widget, or updates to it.

The widget URL protocol

You can access resources within the widget, or potentially other widgets by using the widget URL protocol. Such URLs are of the form:

widget://[widget identifier]/[path]

Use widget.identifier to get the identifier part. One use of this is loading translation files in the widget:

Use a different start file: The widgetfile element

By default, the widget runtime will try to load index.html inside the widget package. You can change this to another file by adding a widgetfile element to the config.xml of the widget:

<widget>
    ...
  <widgetfile>start.html</widgetfile>
    ...
</widget>

Working with preferences

Widgets may store preferences in a persistent manner. When stored, they will be available if you reload or close and reopen the widget. They are deleted when the widget is deleted. See widget.setPreferenceForKey() and widget.preferenceForKey() for details.

//Store the value 'gautamc' for the key 'username'
widget.setPreferenceForKey( 'gautamc', 'username' );
//... close and reopen the widget ...
var username = widget.preferenceForKey('username');
//Retrieve the value again

If you store null for a given key, any previous value for that key will be unset.

//Store the value 'gautamc' for the key 'username'
widget.setPreferenceForKey( 'gautamc', 'username' );
//... do some work ...
if ( logout )
{
  widget.setPreferenceForKey( null, 'username' );
}

Working with widget modes

A widget can be displayed in different modes. The current modes are:

widget

This is the default mode on desktop. The widget has no chrome and is transparent by default.

docked

The widget is displayed in a small mode, suitable in a widget dock or on the idle screen of a mobile.

application

This mode gives the widget a window chrome as decided by the platform. This chrome controls resizing and closing the widget like a normal platform window.

fullscreen

Like application mode, allthough maximized. The widget will cover all the available screen space.

You can request a default mode by giving the defaultmode attribute of the widget element in your config.xml file a value equal to the name of the desired widget.

In order to inform the widget runtime that you support a docked mode, you must give the dockable attribute of the widget element in your config.xml file a value of true.

Which mode is used is decided by the widget runtime.

You can use the widget.widgetMode property to check the current mode of the widget.

When the mode changes, a widgetmodechange will be fired on the widget object. You can listen for it like this:

widget.addEventListener('widgetmodechange', handleModeChange, false);

The event has a mode property which contains the mode the widget is switching to:

function handleMode(e)
{
  switch (e.mode)
  {
    //Handle widget mode
    case 'widget':
    //Handle docked mode
    case 'docked':
    //Handle application mode
    case 'application':
    //Handle fullscreen mode
    case 'fullscreen':
  }
}

You can also use the media query extension -o-widget-mode to deal with mode changes right in your CSS. The -o-widget-mode feature can take a widget name as a value and apply a style only when the widget is in the given mode:

@media all and (-o-widget-mode: application) {
  .fakeChrome {
    display: none;
  }
}

You can test if the platform supports widget modes at all by checking if the property itself is true:

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

Handling changes in screen size

If the resolution of the screen changes, for example when a phone is switched from portrait to landscape mode, a resolution event will be fired on the widget object:

widget.addEventListener('resolution', handleResolutionChange, false);

You can now change the appearance of the widget.

Displaying a status message

Widgets support setting a status message that may be displayed in the widget panel or on some status bar:

var updateInterval = setInterval( function () { window.status = 'Feed last updated ' + new Date (); }, 120000 );

If you set the window.status property to null, it defaults back to the value of window.defaultStatus, which is also settable.

Hiding, showing and closing widgets

Widgets may be hidden in such a way that they do not appear as a window or in the user's task bar. The widget will continue to run in the background. The methods widget.hide() and widget.show() can be used to control this:

hideButton.addEventListener( 'click', function () { widget.hide(); }, false );
//...
if ( newItems )
{
  widget.show();
}

You can use window.close() to close a widget too.

closeButton.addEventListener( 'click', function () {
  window.close();
}, false );

Hiding and closing widgets programatically is not possible on mobile.

Getting the user's attention

You can use the widget.getAttention() and widget.showNotification() methods to notify the user that something has happened in a widget they have installed.

On desktop, widget.getAttention() will blink the widget icon in the taskbar or similar.

if ( requestReceived )
{
  widget.getAttention();
}

On desktop, widget.showNotification() will pop up a notification dialog from the Opera icon in the system tray. The method takes as arguments a message to display, and a callback to call if the user clicks the notification:

if ( itemsReceived )
{
  widget.showNotification( num + ' items received', clickCallkback );
}

This can be used to bring the widget out of hiding for example.

These functions currently do nothing on mobile.

Moving and resizing widgets

Widgets can be moved around and resized beyond the size specified in their config.xml. Use window.moveTo(), window.moveBy(), window.resizeTo() and window.resizeBy(). This means you may for example put your widget into a compact mode and have the user expand it when necessary.

Calling resizeTo will simply change the widget to the given width and height. Calling moveTo will move it to the given x and y coordinates. The following example will move the widget to the top left corner of the screen and make it as large as the screen space allows:

window.moveTo( 0, 0 );
window.resizeTo( screen.availWidth, screen.availHeight );

resizeBy will expand or shrink the widget by the given width and height.

//Increase the size by 200 pixels in both directions
window.resizeBy(200,200);

moveBy will move the widget the distance given as delta_x and delta_y.

//Move the widget 100 pixels in both directions
window.moveBy(100,100);

Moving and resizing widgets is not possible on devices that only show one widget at a time.

• Opera Widgets SDK table of contents

This article is licensed under a Creative Commons Attribution, Non Commercial - No Derivs 2.5 license.