The widget object

Vodafone

This series of compatibility tests is sponsored by Vodafone.

On this page I give a complete overview of the methods and properties of the widget object and their compatibility.

If you want the latest inside scoops on my mobile tests, follow me on Twitter.

See also the main table and the CSS table.

Method or property Opera 9.5 Widget Runtime
on Nokia E66		 Opera 10a Desktop
identifier
 Yes Yes 
widget.identifier

Gives the identifier of the widget. This is a long number, and unfortunately I have no idea where this number comes from or what its function is.
name
 Yes No 
widget.name

The name of the widget as set in the config.xml file.
widgetMode
 Yes Yes 
widget.widgetMode

The current mode of the widget. Values are:

  • application: the widget is running as a full application on a mobile phone.
  • widget: the widget is running as a widget on a desktop computer.
  • docked: the widget is currently docked (minimised).
preferenceForKey()
 Yes Yes 
widget.preferenceForKey(key)

Get the preference stored under key key.
setPreferenceForKey()
 Yes Yes 
widget.setPreferenceForKey(value,key)

Set the preference stored under key key to value.

And yes, the order value,key is completely absurd.
showNotification()
 Yes Yes 
widget.showNotification(msg)

Show message msg in a notification.

A notification is a kind of alert. It’s (supposed to be) slightly more user-friendly than a common alert.
getAttention()
 Yes No 
widget.getAttention()

This method is meant for preventing the screen of a mobile phone to go dark. When it’s called it lights up the screen (again).

This can be useful for widgets where the user spends a long time staring at the screen but not interacting with it. Normally, the screen would darken within, say, 20 seconds, but setting an interval with the getAttention() method prevents this.
hide()
 Yes Yes 
widget.hide()

Hides (minimises or docks) the widget
show()
 No Yes 
widget.show()

Shows (maximises or undocks) the widget.

The Widget Runtime is right in not supporting this method. Widget creators should not be allowed to force a widget on unsuspecting users that want it minimised.
openURL()
 Yes Yes 
widget.openUrl(url)

Opens the URL url in the native system browser. On Nokia phones this is the S60 WebKit, on desktop it’s Opera Desktop.
resolution event
 Yes No 
widget.addEventListener('resolution',fn,false);

where fn is your event handler.

The resolution event fires when the screen orientation changes or the widget mode changes. It does not fire when you use the resizeBy() or resizeTo() methods.
widgetmodechange event
 Yes No 
widget.addEventListener('widgetmodechange',fn,false);

where fn is your event handler.

The widgetmodechange event fires when the widget mode changes (i.e. the user docks or undocks the widget.