|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Object | +--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 following properties and methods were introduced in Opera 9.5. They are not available in 9.2x and below.
All other properties and methods have been available since 9.2x.
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 |
String identifier
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';
Function onHide
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;
}
Function onShow
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;
}
String originURL
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;
String widgetMode
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()
Method Detail |
void getAttention()
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();
}
void hide()
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; )
void openURL( <String> url )
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 );
url
- The URL to open
String preferenceForKey(<String> key)
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');
key
- The preference to get from the preference store
void setPreferenceForKey( <String> value, <String> key )
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' );
value
- The value of the preference
key
- The string to save the preference under.
void show()
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();
}
void showNotification( <String> message, <Function> callback )
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 );
}
message
- Message to display.
callback
- Callback to call when the notification is acted on.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |