Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class widget

    Object
       |
       +--widget

class widget

The widget object

The widget objects contains properties and method which can be used to manipulate the currently running widget. The object is only available to documents which are packaged as widgets, i.e. which are loaded using a config.xml file. It is available in the global scope.

Example:

    widget.setPreferenceForKey('gautamc', 'username');

Roughly, the widget object supplies functions and properties for the following features:

- The widget identity and origin.
- Saving and storing preferences.
- Hiding and showing the widget.
- Getting the user's attention

The following properties and methods were introduced in Opera 9.5. They are not available in 9.2x and below.

- widget.originURL
- widget.identifier
- widget.widgetMode
- widget.onShow
- widget.onHide
- widget.show()
- widget.hide()
- widget.getAttention()
- widget.showNotification()

All other properties and methods have been available since 9.2x.

Defined in widget-object.js

Field Summary
`String` | `identifier` The unique identifier of this widget.
`Function` | `onHide` Function to call when the widget is hidden.
`Function` | `onShow` Function to call when the widget is shown after being hidden.
`String` | `originURL` The URL this widget was downloaded from.
`String` | `widgetMode` The current display of this widget.

Constructor Summary
`widget()` This class does not have a public constructor.

Method Summary
`void` | `getAttention()` Get the user's attention.
`void` | `hide()` Hide the widget.
`void` | `openURL( <String> url )` Open a URL in the web browser.
`String` | `preferenceForKey(<String> key)` Get a preference from the widget preference store.
`void` | `setPreferenceForKey( <String> value, <String> key )` Save a widget preference.
`void` | `show()` Show the previously hidden widget.
`void` | `showNotification( <String> message, <Function> callback )` Show a notification to the user.

Field Detail

### identifier

    String identifier

The unique identifier of this widget. Readonly.

This identifier is a system generated and unique string identifying this widget. It is used as the first part of URLs using the widget URL protocol.

Example:

    img.src = 'widget://' + widget.identifier + '/resources/logo.png';

### onHide

    Function onHide

Function to call when the widget is hidden.

You may set this function to do some kind of processing when the widget is being hidden. An example is stopping the widget from periodically polling some service for data. This function gets called after the widget is hidden with a call to widget.hide().

Example:

    widget.onHide = function ()
    {
        pollInterval = 24000;
    }

### onShow

    Function onShow

Function to call when the widget is shown after being hidden.

You may set this function to do some kind of processing when the widget is being shown after having been hidden. An example is starting to periodically poll some service for data. This function gets called after the widget is shown with a call to widget.show().

Example:

    widget.onShow = function ()
    {
        pollInterval = 12000;
    }

### originURL

    String originURL

The URL this widget was downloaded from. Readonly.

The origin URL represents the unique and stable URL this widget was downloaded from. This property is used in relation to security by allowing or disallowing download from certain URLs. The property can also be used to provide other users with a link to where they can download the widget.

Example:

    a.textContent = 'Learn more about this widget';
    a.href = widget.originURL;

### widgetMode

    String widgetMode

The current display of this widget. Readonly.

The mode is one of 'widget', 'docked', 'application' or 'fullscreen', depending on what mode the widget is currently in. A `widgetmodechange` event will be fired on the widget object if the mode changes.

Example:

    if (widgetMode == 'application')
    {
        removeChrome();
    }

Constructor Detail

### widget

    widget()

This class does not have a public constructor.

Method Detail

### getAttention

    void getAttention()

Get the user's attention.

Calling this method will get the user's attention in some way. This will vary with the device. On desktop, the task bar entry for the widget will blink. Mobile phones which support this may for example flash the display, play a sound or make the phone vibrate.

Example:

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

### hide

    void hide()

Hide the widget.

Calling this method will hide the widget from view. It will not appear as a window or in the task bar, but will continue to run in the background. If the widget is already hidden, calling this method will do nothing.

When the widget is hidden, the widget.onHide function is called.

Example:

    hideButton.addEventListener( 'click', function () { widget.hide(); }, false; )

### openURL

    void openURL( <String> url )

Open a URL in the web browser.

This method lets you programatically open a URL in the browser. The URL is opened in a new tab in the last active window. Only URLs which are allowed by the security policy of the widget may be opened. If the widget's config.xml file or any system configuration disallows access to the the given URL, the call will fail silently.

Example:

    button.addEventListener( 'click', function ()
    {
        color = document.getElementById('colorSelect').value;
        widget.openURL('http://www.buzz.com?color=' + color);
    }, false );

Parameters:

`url` - The URL to open

### preferenceForKey

    String preferenceForKey(<String> key)

Get a preference from the widget preference store.

Get the value stored for the given key in the widget preference store. If there is no value for the given key, an empty string is returned.

Example:

    username = widget.preferenceForKey('username');

Parameters:

`key` - The preference to get from the preference store

Returns:

The value for the key as a String, or an empty String if a value for the key does not exist.

### setPreferenceForKey

    void setPreferenceForKey( <String> value, <String> key )

Save a widget preference.

This method will store the given value in the widget in the widget preference store for the given key. The preference store is unique to this widget and any values stored in it are persisted if the widget is reloaded or closed and started again. If a value for the given key already exists, it is silently overwritten.

Storing an empty string for the given key will create an entry for the given key with an empty string as its value.

Calling this method with `null` as the value will unset any value previously set.

Note that the order of the arguments. This and the name of the method is this way to promote compatibility with Dashboard widgets.

Example:

    widget.setPreferenceForKey( 'gautamc', 'username' );

Parameters:

`value` - The value of the preference

`key` - The string to save the preference under.

### show

    void show()

Show the previously hidden widget.

Calling this method will bring the widget out of hiding, reopening the window and showing it in the task bar for the desktop browser. An example is opening the widget when interesting data or requests were received, by calling widget.show() in the callback to widget.showNotification(). If the widget is already visible, calling this method will do nothing.

When the widget is shown, the widget.onShow function is called.

Example:

    if (dataReceived && showOnNewData )
    {
        widget.show();
    }

### showNotification

    void showNotification( <String> message, <Function> callback )

Show a notification to the user.

Calling this method will show a notification with the given message to the user in some way. This will vary with device. On desktop, a popup similar to messages about new mails.

If the user accepts the notification, for example by clicking on it, the given callback is called. If the user ignores the notification, the callback is never called.

This feature can be used to bring a widget out of hiding when something significant occurs, for example that new weather data has been received.

Example:

    if ( messageReceived )
    {
        widget.showNotification( 'A new message received from ' + message.from, updateView );
    }

Parameters:

`message` - Message to display.

`callback` - Callback to call when the notification is acted on.

Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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