Opera Widgets specification 1.0, third edition
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.
Table of contents
- Opera Widgets specification 1.0, third edition
- Status of this document
- 1. Introduction
- 2. Widget packaging
- 3. Widget configuration file: config.xml
- 4. Widget modes
- 5. Widget scripting interfaces
- 5.1. The widget object
- 5.1.1. Purpose
- 5.1.2. The
identifier
attribute, of typeDOMString
, readonly - 5.1.3. The
originURL
attribute, of typeDOMString
, readonly - 5.1.4. The
widgetMode
attribute, of typeDOMString
, readonly - 5.1.5. The
openURL
() method - 5.1.6. The
preferenceForKey
() method - 5.1.7. The
setPreferenceForKey
() method - 5.1.8. The
getAttention
() method - 5.1.9. The
showNotification
() method - 5.1.10. The
onshow
attribute, of type Function - 5.1.11. The
onhide
attribute, of type Function - 5.1.12. The
show
() method - 5.1.13. The
hide
() method
- 5.2. The
widgetWindow
interface - 5.3. The
WidgetModeChangeEvent
interface - 5.4. The
ResolutionEvent
interface
- 5.1. The widget object
- 6. Widget autodiscovery
- Acknowledgements
- References
- Appendix A: Widget positioning and sizing
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 theapplication
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 valuefalse
, 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 tofalse
, 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, eg1024-2048
, or a comma-separated list of ports, eg80, 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:
- Read the 'width' element from config.xml. If this value is less than the maximum available width, store this value as 'start width'.
- If the 'width' value is larger than the available width, allocate the largest available width, and store it in 'start width'.
- Read the 'height' element from config.xml. If this value is less than the maximum available height, store this value as 'start width'.
- If the 'height' value is larger than the available height, allocate the largest available height, and store it in 'start height'.
- 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:
- 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.
- 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.
- Read the assumed 'start height' value as determined in the sizing algorithm, and continue.
- 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:
- Scan the leftmost vertical line of the widget. If this line only contains transparent pixels, decrease width by one.
- Scan the rightmost vertical line of the widget. If this line only contains transparent pixels, decrease width by one.
- 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:
- Scan the topmost horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
- Scan the bottom horizontal line of the widget. If this line only contains transparent pixels, decrease width by one.
- 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.
Comments
The forum archive of this article is still available on My Opera.