widget-object.js

Summary

Opera Widgets - Core DOM Reference

This document describes the widget object and extensions to the window object which are available to a widget through JavaScript. This API allows you to communicate with the underlying widget runtime. The runtime offers some service 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 web page is running inside a web page, 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 of where the widget was downloaded from is exposed on widget.originURL. One use is for supplying a link to where the user can find more info or updates to the widget.

The widget URL protocol

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

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

Use widget.identifier to get the identifier part. One possibility is loading translation files in the widget:

xhr.open('GET', 'widget://' + widget.identifier + '/resources/i18n.xml', false)

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 the widget.setPreferenceForKey() and widget.preferenceForKey() for details.

widget.setPreferenceForKey( 'gautamc', 'username' ); //Store the value 'gautamc' for the key '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.

widget.setPreferenceForKey( 'gautamc', 'username' ); //Store the value 'gautamc' for the key '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)
    {
        case 'widget':
            //Handle widget mode
        case 'docked':
            //Handle docked mode
        case 'application':
            //Handle application mode
        case 'fullscreen':
            //Handle fullscreen mode

    }
}

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";
  }
}

Widget modes are currently not supported on Opera 9.5 for desktop.

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 supports setting a status message which 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. As per the widget usability guidelines, a widget should have a close button. Any widget uploaded to widgets.opera.com will be rejected if it doesn't have a close button.

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 for notifying the user that something has happened in your widget.

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 a message to display and a callback to call if the user clicks the notification as arguments:

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 moveTo 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.

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

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

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

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




Class Summary
widget The widget object
window Extensions to the window object when running widgets


Documentation generated by JSDoc on Fri Jan 29 17:08:19 2010