|
||||||||
PREV NEXT | FRAMES NO FRAMES |
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.
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.
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)
widgetfile
elementBy 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>
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' );
}
A widget can be displayed in different modes. The current modes are:
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.
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.
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.
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.
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.
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.
File Summary | |
widget-object.js | Opera Widgets - Core DOM Reference |
|
||||||||
PREV NEXT | FRAMES NO FRAMES |