Opera Widgets specification 1.0, third edition

By Opera Software

This is an old version of the Opera Widgets specification 1.0. Unless you have a really specific reason to read this one, you should read the Opera Widgets Specification 1.0 Fourth Edition instead.

Abstract

This document describes Opera Widgets 1.0, third edition, and covers all aspects of Opera Widgets, including the packaging format, the configuration file - config.xml - and scripting interfaces for working with widgets.

Status of this document

This document and its appendices represent the required solutions for creating and running interoperable Opera Widgets across target platforms, both on devices and desktop.

Opera Widgets specification 1.0, third edition

1. Introduction

The purpose of this specification is to provide an implementation reference for Widgets in the Opera browser. The specification builds on the currently implemented features in Opera 9.50.

1.1 Conformance Requirements

The key words ”MUST”, ”MUST NOT”, ”REQUIRED”, ”SHALL”, ”SHALL NOT”, ”SHOULD”, ”SHOULD NOT”, ”RECOMMENDED”, ”MAY”, and ”OPTIONAL” in this document are to be interpreted as described in [RFC2119].

Unless specifically marked otherwise, this document is considered to be normative.

2. Widget packaging

2.1 File format

Widgets are bundled archives of files, as specified by the [ZIP] file format specification, with the exception that the ‘Deflate64’ compression method for the [ZIP] file format is not supported.

2.2 Widget files

Every Opera Widget must contain the following two files:

config.xml – a configuration file containing information necessary to initialize the widget. This file always contains information about the widget’s name and geometry, and may optionally contain more information about the widget, as follows:
- Widget description
- Author information
- Icon reference
- Security information
index.html – this is the main document for the actual widget. It is displayed in a viewport established by the config.xml file. This HTML document can reference external content, including but not limited to scripts, CSS files and images, the same way regular web pages can.

2.3 Widget folder structure

When a widget is packed as a zip file for distribution, the author must choose one of two different ways of structuring the files and folders within the widget:

The config.xml and index.html are put in the root of the .zip file, with any associated resources, such as scripts and images, in the same directory or subdirectories.
An alternative approach is to put all of the files belonging to the widget inside a directory located at the root of the zip file. The name of this folder should be the same as the compressed zip file. When this alternative approach is used, there must not be multiple folders at the root of the zip file's hierarchy. If there are multiple folders at the root, loading the widget must fail.

When a widget is loaded a virtual root path for a file system is established based on the location of config.xml, where this root path is in the same folder as config.xml.

2.4 Content-Type

When widgets are served from web servers, they must be served with the content-type application/x-opera-widgets.

2.5 File extension

Widgets should have the file extension .wgt to be properly recognized as widgets. If, however, the content-type is being used correctly, as above, other extensions such as .zip should work.

3. Widget configuration file: config.xml

The necessary information for a widget UA to run a widget is stored in a file named config.xml, located as previously specified in the Widget packaging chapter of this specification. This file contains information about the widget necessary to establish the initial view for the widget file. A config.xml file is an XML 1.0 document following [XML10]

A minimal config.xml looks like the following, giving the widget a name and making the initial viewport a size of 300×300 CSS pixels:

 <widget>
  <widgetname>
    Hello World!
  </widgetname>
  <width>
    300
  </width>
  <height>
    300
  </height>
</widget>

3.1 White space

When presented to the end user, whitespace characters in config.xml elements are normalized with the following rules:

Leading and trailing whitespace is stripped
Multiple whitespace characters are normalized to single whitespace characters.

This presentation is consistent with setting the value normal for the white-space attribute in [CSS21]

When processing config.xml, Opera will ignore leading and trailing whitespace for all elements, equivalent to getting the textContent DOM attribute value.

3.2 The `widget` element

The widget element is the root element of the config.xml file, and must be present in the widget configuration file as the only element in the document root, as per [XML10].

3.2.1 Optional attributes for the `widget` element

The defaultmode attribute

The defaultmode attribute MAY be present on the widget element, in which case it contains the preferred rendering mode for a widget. Valid attribute values are:

widget: The widget is typically rendered without user chrome, and the widget is assumed to have control over its own window size.
application: The widget is assumed to be rendered in a viewport size determined by the widget engine, optionally using the initial rendering dimensions specified in config.xml as a suggestion. Furthermore, where applicable the widget engine should also render application chrome.
fullscreen: This mode is identical to the application mode, except that the widget is expected to be rendered using the entire available viewport. A user agent may render the widget using application chrome.

If the specified rendering mode is not available to the widget, the widget should fall back to render in another mode, in the order application, fullscreen, widget.

If the attribute is missing, it is assumed to be present with the value widget.

The dockable attribute

The dockable attribute specifies whether the widget supports full docking, where a web document is displayed, as opposed to displaying limited information consisting of for example the Widget status, title and icon.

Valid values for the dockable attribute are case sensitive strings - the values 'yes', 'true' and 'dockable' represent dockable widgets. All other values are to be interpreted as the value false, meaning the widget is not providing a web document as it's docked mode.

The transparent attribute

If a widget does not require transparency features, ie the preferred presentation is for the entire widget viewport to be opaque, the transparent attribute can be used to control the widget's use of transparency.

Valid values for the transparent attribute is a case sensitive string, having the values 'yes', 'true' and 'transparent' representing transparent widgets. All other values must be interpreted as 'false', meaning the widget will not be transparent.

If the attribute is missing, and the current computed widget mode is 'widget', it is assumed to be present with the value transparent, hence implying that the default presentation is to support transparency. If the computed value of the widget mode is 'application' or 'fullscreen', the widget is expected to default to false, not supporting transparency. A user agent may override these values, depending on platform requirements.

3.3 Required child elements of `<widget>`

3.3.1 The `widgetname` element

The widgetname element must be present in config.xml as a child of the widget element, and must contain a string whose purpose is to provide a human-readable title for the widget. This title will be used in application menus to provide a descriptive title for the widget.

3.3.2 The `width` element

The width element should be present in config.xml as a child of the widget element. After whitespace normalization, and stripping of any leading/trailing white-space the value of this element must be interpretable as a string representation of an integer, containing only the characters [0–9].

This integer value is treated as the widget’s size along the horizontal axis, measured in CSS pixels, as per section 4.3.2 of [CSS21], and should represent the inner width of the widget, or the entire drawable area along the horizontal axis.

If the attribute is missing or its value is invalid, it is assumed to be present with a value of 100.

Please see the note on virtual viewports when implementing on a target where chromeless windows cannot be dragged offscreen.

3.3.3 The `height` element

The height element should be present in config.xml as a child of the widget element. After whitespace normalization, and stripping of any leading/trailing white-space the value of this element must be interpretable as a string representation of an integer, containing only the characters [0–9].

This integer value is treated as the widget’s size along the vertical axis, measured in CSS pixels, as per section 4.3.2 of [CSS21], and should represent the inner height of the widget , or the entire drawable area along the horizontal axis.

If the attribute is missing, or its value is invalid, it is assumed to be present, with a value of 100.

Please see the note on virtual viewports when implementing on a target where chromeless windows cannot be dragged offscreen.

3.4 Optional child elements of `<widget>`

3.4.1 The `widgetfile` element

The widgetfile element is an optional child element of the widget element. If present, the purpose of this element is to point the widget to an alternative start file for the widget. When present, the element must contain a valid relative path reference to an alternative start file for the widget. The path reference must be URL encoded.

3.4.2 The `author` element

The author element is an optional child element of the widget element. If present, the purpose of the element is to provide information about the widget’s author. This element has a few child elements, as specified below.

3.4.2.1. The `name` element

If the name element is present in the document, this element should be present as a child element of the author element. If present, this element must be a child of the author element, and its value must be a string that contain a human-readable representation of the widget author’s name.

3.4.2.2. The `organization` element

If the organization element is present in the document, this element may be present as a child element of the author element. If present, this element must be a child of the author element, and its value must be a string that contains a human-readable name for an organization representing, or represented by the widget author.

3.4.2.3. The `email` element

If the email element is present in the document, this element may be present as a child element of author. When present, this element must contain a string, whose value should be a valid e-mail adress as specified by [RFC2822]. This e-mail address should be a live e-mail address widget users can use to contact the widget author.

3.4.2.4. The `link` element

If the link element is present, the link element may be present as a child element of author. If the link element is present, this element must contain a string, whose value must be a syntactically valid IRI as specified by [RFC3987]. It is further recommended that the IRI represented also resolves. The intended presentation to an end-user is to present this IRI as a link the user can visit.

3.4.3 The `description` element

The description element is an optional child element of the widget element. If present, the element should contain a string that serves as a human-readable short plain-text description of the widget.

3.4.4 The `icon` element

The icon element is an optional child element of the widget element. The purpose of this element is to provide a pointer to an icon file contained within the widget archive, which the underlying operating system and widget player can display to the end user in places where displaying an application icon is natural.

The element must contain a string that is a relative IRI in accordance with [RFC3987], with the root path being the same as the location of the config.xml file.

When present, the IRI must resolve, and must reference an image in either of the following formats: [PNG10], [GIF89] or [SVG].

The icon element can optionally have width and height attributes.

config.xml may contain more than one icon element. If multiple icon elements are present, the widget engine may choose the icon that best matches the display requirements of the widget engine, even if none of the specified icons exactly match the size.

width: The value of width is an unsigned integer, representing the desired width of the icon in device pixels.
height: The value of height is an unsigned integer, representing the desired height of the icon in device pixels.

When the user agent chooses an icon, it should select the icon that most closely matches the size implied by the width and height attributes. If there are no matches, the User Agent should choose the one closest to matching the size.

If multiple icon elements with the same size exist, Opera should choose the last of the icons present in config.xml, although a widget engine may choose to always use an icon in a particular format, such as PNG, even when an appropriately sized icon exists in another format.

3.4.5 The `security` element

The security element is an optional child element of the widget element and may be present in the document. The purpose of the security element is to act as a container for security-related settings in a widget. The child elements of the security element are described below.

3.4.5.1. The `access` element

The access element is an optional child element of the security element. The child elements of access declare which protocols, hosts, ports, and paths the widget may use. Missing child elements are interpreted to mean “any”. An example is that if the host element is missing, the widget will request access to all hosts.

Furthermore, all of the specified child elements may occur multiple times, and the product of all these is used. The child elements are as defined below.

protocol: The protocols the widget will be using to contact external servers. All protocols except the file protocol are permitted.
host: The host element establishes which hostnames may be contacted. The hostnames are exact matches. This means that a widget specifying www.example.com must not be able to contact example.com. IP addresses may also be used as values.
port: The port element establishes which port numbers the widget will be using. The value is either a number, a range of numbers separated by a dash, eg 1024-2048, or a comma-separated list of ports, eg 80, 1337.
path: The path element specifies the path part of the URI a widget may contact.

3.4.5.2. The `content` element

Widgets may use third-party plugins, and Java content. Widgets that want to use these features must request this access by adding an optional content element as a child of the security element. When present, the content element must contain at least one of the two attributes specified below, and it may contain both.

java attribute: The possible values of this attribute are the case-insensitive strings "yes" and "no". When a widget wants access to use Java content embedded in the widget, the value of this attribute _must_ be "yes". If the java attribute is not present, the attribute is assumed to be present, and have the associated value "no".
plugin attribute: The possible values of this attribute are the case-insensitive strings "yes" and "no". When a widget wants access to use plugin content embedded in the widget, the value of this attribute _must_ be "yes". If the plugin attribute is not present, the attribute is assumed to be present, and have the associated value "no".

If a content element is not present in a config.xml’s security section, or if a security section is not present in a widget, the element is assumed to be present with the values of both java and plugin set to ”no”.

3.4.5.3. Security model

The widget access model is summarised as follows:

Widgets do not have access to content residing on a user’s file system using the file: protocol
Widgets may access content over http, even when such access is not explicitly requested through the protocol element in config.xml
Widgets may not use any other protocol without prior declaration. Widgets may access content over https, ftp or other supported protocols (except file: as previously noted), but only if the widget has declared this in the security section of config.xml.
Widgets may not contact non-default ports, except when pre-declared in config.xml. Furthermore, widgets may not contact non-default ports equal to or below 1023.
A widget that has contacted an intranet as defined below must not be able to contact addresses not defined as being intranets. Likewise, widgets interacting with hosts outside the IPv4 ranges specified below must not be allowed to interact with these IP ranges.

3.4.5.4. Intranet definition

An intranet is defined based on the resolved IPv4 address of a host name. The following IPv4 ranges are defined as intranets:

10.0.0.0 to 10.255.255.255
172.16.0.0 to 172.31.255.255
192.168.0.0 to 192.168.255.255
169.254.0.0 to 169.254.255.255

All other IP ranges than these are defined as Internet addresses.

3.4.5.5. Security example

The following example shows a security section specifying that the widget should be allowed to contact the domains example.com and example.org using either the https or http protocols, but only through the path ’/good’ on ports 80,1337 and ports in the range 2048–4096. In addition, the widget wants access to Java, but not plugins.

 <security>
  <access>
    <protocol>http</protocol>
    <protocol>https</protocol>
    <host>example.com</host>
    <host>example.org</host>
    <path>/good</path>
    <port>2048-4906</port>
    <port>80,1337</port>
  </access> <content java="yes" plugins="no" />
</security>

3.4.6 The `id` element

The id element is an optional child element of the widget element. If present, this element may be used to establish a concept of identity for the widget that may be used for recognizing version updates and similar. The syntax requirement for this element is to have three required child elements, containing strings, as specified below.

host: This element is required, and must be a fully qualified domain name specifying the host from which the widget was downloaded.
name: This element is required, and must be a string unique to the domain specified in the host element.
revised: This element is required, and must be a string in the [W3CDTF] format, with the added constraint that both year and month are made mandatory parts of the date. The date used should be a date chosen by the author, with enough granularity to represent two different dates, and with the exception that both Year and Month are made mandatory.

4. Widget modes

Widgets are client-side web applications for displaying local or remote content, typically on a user desktop, or appearing as locally installed applications on a device. Widgets can be displayed in several different contexts, or modes, as described below. An installed widget may support several of the modes, but will only display one at a time.

widget: The widget mode typically describes traditional desktop widgets - applications displayed without application chrome such as resizing controls or title bars. Widgets displaying in this mode are typically expected to be in control of their own rendering environment, meaning they can set or reset their size at will. On targets where the widget does not fit, the platform is expected to provide a scrolling mechanism or other means of navigating around the widget, while still allowing the widget to be rendered and displayed according to the geometric information the widget has made available.
application: The application mode typically describes widgets that, on a system with window managment, will display chrome and controls for moving or resizing the widget. Widgets in this mode are expected to have the window/widget size controlled by the end-user or operating environment, but the widget may suggest initial layout information.
fullscreen: This mode is equal to the application mode, except that the initial default size provided by the runtime environment is expected to be full screen, or what equates to a 'maximized' mode for desktop application.
docked: The dock mode, sometimes referred to as 'microwidget mode', is a mode wherein the widget typically renders and displays in a minimized state, such as an idle screen, list view, or other types of display where the widget has more limited size. Typically, widgets in this mode are not expected to be interactive, and the user can only interact with the widget through activating it, and thus switching it into one of the previously defined modes.

4.1 CSS extensions for widget modes

Widget authors that wish to style widgets separately in different modes may use the -o-widget-mode CSS media feature, which makes use of the four previously defined widget modes as values to specify what widget modes the styling should be applied to. Some examples follow:

Hiding UI elements in application mode:


@media all and (-o-widget-mode:application) {
  /* We don't need to display fake user chrome controls, since
     real chrome is provided */
  .fakeChrome { display: none; }
}

Changing the font-size for the docked (microwidget) mode


@media all and (-o-widget-mode:docked) {
  body { font-size: 80%; }
}

It is also possible to specifically style something when the platform supports the -o-widget-mode attribute, by not specifying a value:


@media all and (-o-widget-mode) {
  div.friendlyMessage {
    content: "I will be displayed if I am a modern widget";
  }
}

5. Widget scripting interfaces

5.1 The widget object

5.1.1 Purpose

The purpose of the widget object is to expose functionality specific to widgets that either should not or must not be available to scripts running on regular web pages. The widget object implements the Widget interface:

interface Widget {

    readonly attribute DOMString identifier;
    readonly attribute DOMString originURL;
    readonly attribute DOMString widgetMode;

    void openURL(in DOMString URL);
  String preferenceForKey(in DOMString key);
    void setPreferenceForKey(in DOMString value,
                              in DOMString key);

    /* Widget attention */
    void getAttention();
    void showNotification(in DOMString msg, in Function callback);

    /* Widget window managment; */
         attribute Function onshow;
         attribute Function onhide;
    void show();
    void hide();
}

5.1.2 The `identifier` attribute, of type `DOMString`, readonly

The identifier attribute, of type DOMString, serves as a universally unique identifier of the widget instance in question. The value must always contain a valid, unique DOMString.

5.1.3 The `originURL` attribute, of type `DOMString`, readonly

When a widget is downloaded and instantiated from any protocol other than file://, the value of this attribute should always be a valid URL locating the widget. The value of the attribute should not be escaped, or otherwise encoded.

5.1.4 The `widgetMode` attribute, of type `DOMString`, readonly

The widgetMode attribute identifies the current rendering mode for the widget. The value of this attribute should be one of the values widget, application, fullscreen or docked. The value must always correspond to the current rendering mode of the widget.

5.1.5 The `openURL`() method

The openURL() method of the widget object takes a String as an argument, which must be a valid URL as defined by [RFC3987]. When this method is called with a valid URL, the URL should be opened in the system browser of the system on which the widget runs.

Note that restrictions on what URLs can be opened using openURL apply, as defined in the security section of this specification. Specifically this means the following are true:

Widgets cannot open URLs in the file: domain
Widgets that have contacted the non-routable IPv4 address ranges as specified cannot use openURL to open URLs in IPv4 ranges other than those specified
Likewise, widgets that have contacted addresses outside the four non-routable address cannot use openURL to open URLs within the specified ranges.
OpenURL does not accept relative IRI’s and as such cannot open any files stored inside the widget.

5.1.6 The `preferenceForKey`() method

The preferenceForKey() method takes a String argument, key. When called, this method returns a string that has previously been stored with the setPreferenceForKey method, or undefined if the key key does not exist.

5.1.7 The `setPreferenceForKey`() method

The setPreferenceForKey() method takes two String arguments, preference and key. When called, this method takes the string in the preference argument, and stores it with the key named in the key argument for later retrieval using the preferenceForKey() method. To delete a previously stored key, the setPreferenceForKey() method is called with the value null in the preference argument, and the name of the key to be deleted in the key argument.

5.1.8 The `getAttention`() method

The getAttention() method takes no arguments and returns void. When called, this method should use an appropriate means to bring the widget to the user's attention.

Methods of bringing the user's attention to the widget may for instance include flashing the taskbar icon, or raising the widget's urgency. The getAttention() method should not, however, try to grab the window focus.

5.1.9 The `showNotification`() method

The showNotification() method takes two arguments, the first being a String with the message text, and a second argument being a function that acts as a callback when the notification is accepted.

When showNotification() is called, the system is expected to display a notification containing the message text. The message text is a DOMString and whitespace within the string; including newlines is significant.

Upon the user acknowledging the notification, the callback function is called without any arguments.

5.1.10 The `onshow` attribute, of type Function

When a function is specified in the onshow callback, eg the value of the attribute is non-null and a valid function reference, the callback will be called whenever the widget's state changes from being hidden to being visible.

Note that the onshow callback should not be dispatched if a visible widget gets focus.

5.1.11 The `onhide` attribute, of type Function

When a function is specified in the onhide callback, eg the value of the attribute is non-null and a valid function reference, the callback will be called whenever the widget's state changes from being visible to being hidden.

Note that the onshow callback should not be dispatched if a visible widget loses focus.

5.1.12 The `show`() method

The show() method takes no arguments, and returns no value. When the method is invoked a widget that has previously been in a hidden state will be shown. If the widget is already in a shown state, invoking show will perform no action.

5.1.13 The `hide`() method

The hide() method takes no arguments, and returns no value. When the method is invoked a widget that has previously been in a shown state will be hidden. If the widget is already in a hidden state, invoking show will perform no action.

The show() method takes no arguments.

5.2 The `widgetWindow` interface

A widget's initial dimensions are controlled by the width and height elements in the config.xml file. In addition to this, a widget can be resized dynamically with JavaScript, using the extensions listed below.

interface widgetWindow {

         attribute DOMString status;
         attribute DOMString defaultStatus;

    void moveTo(in Integer pos_x, in Integer pos_y);
    void moveBy(in Integer delta_pos_x, in Integer delta_pos_y);
    void resizeTo(in Integer x_size, in Integer y_size);
    void resizeBy(in Integer delta_x_size, in Integer delta_y_size);
  }

5.2.1 The `status` attribute, of type DOMString

The status attribute is used to display a status message in a widget overview/managment page, or similar. It is used to display a short piece of textual information to the user. An example could be a stock ticker that changes to show the value of the last updated stock, and then reverts to displaying a default status message.

When set, the status message is kept until it is either cancelled by clicking in the widget document that set the status, or the value of the attribute is set to an empty string.

5.2.2 The `defaultStatus` attribute, of type DOMString

The defaultStatus attribute, when set, provides a default status message to be displayed in a widget managment page, or other widget overview mechanism.

When the value of this attribute is non-null, an action that cancels window.status should bring up the contents of the defaultStatus attribute in place of the original/system-provided status message. If the value is null or an empty string, the widget runtime should fall back to a system-provided message.

5.2.3 The `moveTo`() method

When the widget is rendering in a context where the position of the widget may be changed, the moveTo() method sets the position of the widget. The method accepts two integer values as arguments, pos_x and pos_y, which are x and y coordinates defined by a coordinate system. The system used is a flat cartesian surface whose origin (0,0) is at the top left corner of the available viewport - the coordinate space has x values increasing when going right, and y values increasing when going down.

5.2.4 The `moveBy`() method

When the widget is rendering in a context where the position of the widget may be changed, the moveBy() method moves the widget in the x and/or y direction, using as arguments the integer values delta_pos_x and delta_pos_y, defined by a coordinate system. The system used is a flat cartesian surface whose origin (0,0) is at the top left corner of the available viewport - coordinate space has x values increasing when going right, and y values increasing when going down. Negative values for both arguments are accepted, and a negative value for either argument means that the widget should move towards respectively the top or the left of the viewport.

;5.2.5 The `resizeTo`() method

When the widget is rendering in a context where the size of the widget may be changed, the resizeTo() method sets the new size of the widget, using the Integer arguments size_x and size_y for the new width and height. Setting the size using resizeTo() must produce exactly the same dimensions for the widget as they would if they appeared in the config.xml width and height elements. Both the size_x and size_y argument values must be larger than 1, and a call to resizeTo() with smaller values should result in no change to the widget dimensions.

5.2.6 The `resizeBy`() method

The resizeBy() method should resize the widget by adding the value of the argument delta_x_size to the current value for the widget width, and adding the value of the argument delta_y_size to the current height of the widget, measured in pixels. The resulting dimensions gathered from such an addition must produce exactly the same dimensions for the widget, as they would if the calculated dimensions appeared in the config.xml width and height elements. Negative values for both arguments are accepted, as long as the resulting calculated size remains larger than 1×1 pixels, in which case the resizeBy() method should result in no change to the widget size.

5.2.7 Storing geometric information

When a successful resize of the widget has been performed using any of the four methods mentioned, the resulting values should be stored, and used in place of any values specified in config.xml.

5.3 The `WidgetModeChangeEvent` interface

When the value of the -o-widget-mode CSS attribute changes, the widgetmodechange event is dispatched on the Widget object. When the event is dispatched, the event object passed as an argument to the event listener must have a widgetMode attribute that corresponds to the current rendering mode. The value must be one of those mentioned for the widgetMode attribute on the Widget interface.

The WidgetModeChangeEvent event must not bubble, must not be cancelable and must implement the Event interface [DOM3Events]. The event has no namespace (Event.namespaceURI is null).

interface WidgetModeChangeEvent : Event {
  readonly attribute DOMString widgetMode;
  void initMediaTypeChangeEvent(in DOMString typeArg,
                                in boolean canBubbleArg,
                                in boolean cancelableArg,
                                in DOMString widgetModeArg);

  // For DOM Level 3 support
  void initMediaTypeChangeEventNS(in DOMString namespaceURI,
                                  in DOMString typeArg,
                                  in boolean canBubbleArg,
                                  in boolean cancelableArg,
}

5.4 The `ResolutionEvent` interface

The ResolutionEvent event is dispatched on the widget object when the width or height values of the attached display object changes. It must not bubble, must not be cancelable and must implement the Event interface [DOM3Events]. The event has no namespace (Event.namespaceURI is null).

When dispatched, the event object must have two attributes, width and height, which correspond to the new available width and height for the widget. These two values should correspond to the values availWidth and availHeight on the Screen interface.

interface ResolutionEvent : Event {
  readonly attribute int width;
  readonly attribute int height;
  void initMediaTypeChangeEvent(in DOMString typeArg,
                                in boolean canBubbleArg,
                                in boolean cancelableArg,
                                in int widthArg,
                                in int heightArg);

  // For DOM Level 3 support
  void WidgetModeChangeEventNS(in DOMString namespaceURI,
                               in DOMString typeArg,
                               in boolean canBubbleArg,
                               in boolean cancelableArg,
                               in int widthArg,
                               in int heightArg);
}

6. Widget autodiscovery

6.1 Purpose

The purpose of Widget autodiscovery is to enable clients who know the URI of a web page to identify and find the location of a widget associated with said web page. A widget-aware web client should offer a mechanism that exposes the presence of the widget to the user, and a mechanism for installing the widget.

6.2 Definition

A Widget autodiscovery element is a link element, as defined in section 12.3. of [HTML401]. As with other link elements, an autodiscovery element may appear in the head element of an HTML or XHTML document, but it must not appear inside the body element. An example autodiscovery element looks like this:

 <link
  type="application/x-opera-widgets" rel="alternate"
  href="http://widgets.example.com/example.zip" title="An Example
  Widget"
/>

6.3 Relationship to HTML and XHTML

6.3.1 Syntax rules inherited from HTML and XHTML

When a widget autodiscovery element appears in a [HTML401] or [XHTML10] document, the element shares all the syntax rules and restricitions of other markup elements.

6.3.2 Multiple autodiscovery elements

A document may contain multiple autodiscovery elements. A User Agent should present an installation option for all autodiscovered widgets to the user, listed in the order of appearance in the source code.

A User Agent that only presents one autodiscovered widget to the user should choose the first autodiscovered widget for installation whenever the user opts to install the widget.

6.4 Required attributes

6.4.1 The type attribute

The type attribute must be present in a widget autodiscovery element. The value of the type attribute must be an Internet Media type, and the media type must be application/x-opera-widgets.

6.4.2 The rel attribute

The rel attribute must be present in a widget autodiscovery element. As defined in section 6.12 of [HTML401], the value of the rel attribute is a space-separated list of keywords. The list of keywords must include the keyword alternate in uppercase, lowecase, or mixed case.

6.4.3 The href attribute

The href attribute must be present in a widget autodiscovery element, and its value must be the URI of the widget. The value may be a relative URI, and if so, clients must resolve it to a full URI, using the document’s base URI. The URIs must conform to [RFC3987].

6.5 Optional attributes

6.5.1 The title attribute

The title attribute may be present in a widget autodiscovery element. A User-Agent should treat the value of the title attribute as a human-readable title for the widget, and the User-Agent may present this title to the user.

Acknowledgements

The specification for the widget object builds on Apple’s [Dashboard] reference.

Widget Autodiscovery in large parts builds on the [AtomAutodiscovery] specification.

References

[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997. RFC2119 is available at http://www.ietf.org/rfc/rfc2119
[ZIP]: .ZIP File Format Specification. PKWare Inc., January 2006 The .ZIP File Format Specification is available at http://www.pkware.com/business_and_developers/developer/popups/appnote.txt
[XML10]: Extensible Markup Language (XML) 1.0 (Third Edition). Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, François Yergeau. W3C, February 2004. Extensible Markup Language (XML) 1.0 specifciation is available at http://www.w3.org/TR/REC-xml/
[CSS21]: Cascading Style Sheets, level 2 revision 1; CSS 2.1 Specification. Bert Bos, Ian Hickson, Tantek Çelik, Håkon Wium Lie. W3C, April 2006. The CSS 2.1 Specification can be found at http://www.w3.org/TR/CSS21/
[RFC3987]: Internationalized Resource Identifiers (IRIs) . M. Duerst, M. Suignard. IETF, January 2005. RFC3987 is available at http://www.ietf.org/rfc/rfc3987
[Dashboard]: Dashboard Reference. Apple Computer, Inc, May 2006. The Apple Dashboard Reference is available at http://developer.apple.com/documentation/AppleApplications/Reference/Dashboard_Ref/index.html
[HTML401]: HTML 4.01 Specification, Dave Raggett, Arnaud Le Hors, Ian Jacobs. W3C, December 1999. The HTML 4.01 Specification is available at http://www.w3.org/TR/html401/
[XHTML1]: XHTML™ 1.0 The Extensible HyperText Markup Language (Second Edition), S. Pemberton et al. W3C, January 2000. The XHTML 1.0 specification is available at http://www.w3.org/TR/xhtml1/
[AtomAutodiscovery]: Atom Autodiscovery (draft), M. Pilgrim, P. Ringnalda. ATOMPUB Working Group, May 2005-. The Atom Autodiscovery specification draft is available at http://philringnalda.com/rfc/draft-ietf-atompub-autodiscovery-01.html
[SVG]: Scalable Vector Graphics (SVG) 1.1 Specification, Jon Ferraiolo, 藤沢淳 (FUJISAWA Jun), Dean Jackson. W3C. The SVG 1.1 specification is available at http://www.w3.org/TR/SVG/

Appendix A: Widget positioning and sizing

This appendix to the widget specification provides algorithms to determine widget size and position, for cases where either the window manager provides the initial widget size, or on platforms where widgets need to separate the concepts of "viewport size" and "widget size".

6.6 Algorithm for widget sizing

The following algorithm is used for determining the start size of a widget.

The config.xml file is opened
Read the 'defaultmode' attribute of the widget element in config.xml
If the widget has been started in the past, and the defaultmode value is 'widget', read the stored 'start width' and 'start height' values, and go to step 11
If the widget has been started in the past, and the defaultmode is 'application', and the value of 'start width' exceeds the available rendering surface width (In other words, when the geometry of the rendering surface has changed), let the 'start width' be equal to the available rendering surface width, and continue to the next step.
If the widget has been started in the past, and the defaultmode is 'application', and the value of 'start height' exceeds the available rendering surface height (In other words, when the geometry of the rendering surface has changed), let the 'start width' be equal to the available rendering surface width, and continue to step 11.
If the value for defaultmode is 'fullscreen', and the widget supports the concept of fullscreen/maximized applications, let the 'start width' and 'start height' values be determined by the maximum available rendering surface width and height, and go to step 11.
If the value for defaultmode is 'fullscreen', and the runtime does not support the 'fullscreen' mode, but supports the 'application' mode, assume that the defaultmode is 'application' and go to step 8.
If the value for defaultmode is 'application', and the runtime does not support the 'application' mode, but supports 'fullscreen', assume that the defaultmode is set to 'fullscreen' and go to step 5.
If the value for defaultmode is 'application' and the platform supports the mode, and allows widgets to set their own size:
1. Read the 'width' element from config.xml. If this value is less than the maximum available width, store this value as 'start width'.
2. If the 'width' value is larger than the available width, allocate the largest available width, and store it in 'start width'.
3. Read the 'height' element from config.xml. If this value is less than the maximum available height, store this value as 'start width'.
4. If the 'height' value is larger than the available height, allocate the largest available height, and store it in 'start height'.
5. Continue to step 11.
If the value for defaultmode is one of 'application' or 'fullscreen', and neither mode is supported by the widget runtime, assume that the value is 'widget' and continue to step 10.
If the application mode is 'widget' and the mode is supported by the runtime, use the values of the 'width' and 'height' element as values for 'start width' and 'start height', respectively, and go to step 10.
Determine the initial widget position as described in the algorithm below. Create a widget window using the widgets 'start width' and 'start height', as described as the initial start width and height, and start the widget. Store the 'start width' and 'start height' values permanently.

6.7 Determining the initial widget position

Use the following algorithm to determine the initial widget position

If the widget has been started before, go to step 4.
Let the initial rendering position of the widget be determined by the upper left corner, using the values 'start_x' and 'start_y'
If the widget has the defaultmode 'widget', determine the initial position as thus:
1. Read the assumed 'start width' value as determined in the sizing algorithm. If the width of 'start width' is equal to, or larger than the width available to the widget, let the widget's upper left start position, 'start x', be 0, and continue to step 3.3.
2. If the assumed 'start width' value is less than the available width, let the value 'start_x' be calculated according to the following formula: start_x = (available width-start width)/2. Otherwise, let the start_x value be 0.
3. Read the assumed 'start height' value as determined in the sizing algorithm, and continue.
4. If the assumed 'start height' value is less than the available height, let the value 'start_y' be calculated according to the following formula: start_y = (available height-start height)/2. Otherwise, let the start_y value be 0.
Position the widget according to the start_x and start_y values, and display the widget.

6.8 Other

These are implementation guides for resizing, positioning and widget types; this algorithm is considered informative.

On window managers that support window states like 'maximized' and 'restored/unmaximized', assume that the 'fullscreen' mode equals the 'maximized' mode, and that 'application' equals 'restored/unmaximized' mode.
When a widget is moved or resized using windows.move(To|By), and windows.resize(To|By), use the new values for widget size and position as determined after these method calls as new values for 'start width', 'start height', 'start_x', and 'start_y'. These values should be stored and used when a widget is started again.
The widget's own dimensions must be respected for widgets rendering using the 'widget' rendering mode.
When the widget is an application or fullscreen widget, the widget runtime may ignore calculated positioning and sizing information.

6.9 Virtual viewport resizing

Certain window managers and systems may not allow chromeless windows to be dragged off the viewport, leaving the widget with little surface area in which the user can move the widget. This section describes an algorithm to mitigate the problem. On such platforms, this algorithm, or a workalike must be implemented to facilitate a good user experience.

Relation to the width element

Note that the width element represents the canvas width, and not the window width. Under most circumstances, the window width and canvas width should be the same, but certain platforms may implement a window width that is different from the canvas width, using the following algorithm:

If the window manager does not allow chromeless windows to be dragged off the desktop, Opera may resize the window according to the following algorithm:
1. Scan the leftmost vertical line of the widget. If this line only contains transparent pixels, decrease width by one.
2. Scan the rightmost vertical line of the widget. If this line only contains transparent pixels, decrease width by one.
3. Repeat 1) and 2) until the first non-transparent pixel is found
The recalculated window width must not, under any circumstance cause visible pixels to be clipped from the widget.

Relation to the width element

Note that the height element represents the canvas height, and not the window height. Under most circumstances, the window height and canvas height should be the same, but certain platforms may implement a window height that is different from the canvas height, using the following algorithm:

If the window manager does not allow chromeless windows to be dragged off the desktop, Opera may resize the window according to the following algorithm:
1. Scan the topmost horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
2. Scan the bottom horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
3. Repeat 1) and 2) until the first non-transparent pixel is found
The recalculated window height must not, under any circumstance cause visible pixels to be clipped from the widget.

This article is licensed under a Creative Commons Attribution, Non Commercial - Share Alike 2.5 license.

Opera Widgets specification 1.0, third edition

Abstract

Status of this document

Table of contents

1. Introduction

1.1 Conformance Requirements

2. Widget packaging

2.1 File format

2.2 Widget files

2.3 Widget folder structure

2.4 Content-Type

2.5 File extension

3. Widget configuration file: config.xml

3.1 White space

3.2 The widget element

3.2.1 Optional attributes for the widget element

3.3 Required child elements of <widget>

3.3.1 The widgetname element

3.3.2 The width element

3.3.3 The height element

3.4 Optional child elements of <widget>

3.4.1 The widgetfile element

3.4.2 The author element

3.4.2.1. The name element

3.4.2.2. The organization element

3.4.2.3. The email element

3.4.2.4. The link element

3.4.3 The description element

3.4.4 The icon element

3.4.5 The security element

3.4.5.1. The access element

3.4.5.2. The content element