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.