Copyright © 2009 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This specification defines a set of APIs and events for the Widgets 1.0 Family of Specifications that enable baseline functionality for widgets. The APIs and Events defined by this specification defines, amongst other things, the means to:
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
First Public Working Draft of the Widgets 1.0: APIs and Events specification.This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is produced by the Web Applications WG, part of the Rich Web Clients Activity in the W3C Interaction Domain. It is expected that this document will progress along the W3C's Recommendation track. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
You can find the latest Editor's Draft of this document in the W3C's CVS repository, which is updated on a very regular basis. Please send comments to public-appformats@w3.org, the W3C's public email list for issues related to Web Application Formats. Archives of the list are available. A detailed list of changes from the previous version is also available from the W3C's CVS server.
Implementers should be aware that this document is not stable. Implementers who are not taking part in the discussions are likely to find the specification changing out from under them in incompatible ways. Vendors interested in implementing this document before it eventually reaches the Candidate Recommendation stage should join the aforementioned mailing lists and take part in the discussions.
User agents that wish to extend this specification in any way are encouraged to discuss their extensions on a public forum, such as public-webapps so their extensions can be considered for standardization.
WindowWidget Interface
Widget Interface
currentMode
Attributelocale Attributeidentifier AttributecurrentIcon AttributeauthorName AttributeauthorEmail AttributeauthorURL Attributename Attributedescription Attributeversion Attributewidth Attributeheight Attributepreferences AttributesetPreference() MethodgetPreference() Methodhide() Methodshow() Methodonmodechange Callbackonbeforeupdate Callbackonafterupdate CallbackhasFeature() Methodicons AttributesetIcon() MethodopenURL() MethodgetAttention() MethodshowNotification() MethodWidgetIcon interface
This specification defines a set of APIs and events for widgets that enable baseline functionality for widgets. Widgets are full-fledged client-side applications that are authored using Web standards. They are typically downloaded and installed on a client machine or device where they typically run as stand-alone applications outside of a Web browser. Examples range from simple clocks, stock tickers, news casters, games and weather forecasters, to complex applications that pull data from multiple sources to be "mashed-up" and presented to a user in some interesting and useful way (see [Widgets-Landscape] for more information). The runtime environment in which a widget runs is referred to as a widget user agent.
This section is non-normative.
This specification is part of the Widgets 1.0 family of specifications, which together standardize widgets as a whole. The Widgets 1.0: Packaging and Configuration [Widgets-Packaging] standardizes a Zip-based packaging format, an XML-based configuration document format and a series of steps that user agents follow when processing and verifying various aspects of widgets. The Widgets 1.0: Digital Signature [Widgets-DigSig] specification defines a means for widgets to be digitally signed using a custom profile of the XML-Signature Syntax and Processing Specification. The Widgets: 1.0: Automatic Updates [Widgets-Updates] specification defines a version control model that allows widgets to be kept up-to-date over [HTTP].
As well as sections marked as non-normative, all diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words must, must not, required, should, should not, recommended, may and optional in this specification are to be interpreted as described in [RFC2119].
This specification describes the conformance criteria for user agents (relevant to implementers) and various resource types (relevant to authors and authoring tool implementers).
There is only one class of product that can claim conformance to this specification: a user agent.
A user agent is an implementation that attempts to support this specification.
Note: The user agent described in this specification does not denote a "widget user agent" at large. That is, a user agent that implements all the specifications, and dependencies, defined in the Widgets 1.0: Family of Specifications. The user agent described is this specification is only concerned with the behavior of programming interfaces and what causes events to be fired.
A user agent must behave as described by this specification in order to claim conformance.
This specification relies on several other specifications. A specification is said to be supported by a user agent if the user agent attempts to implement that specification.
A user agent MUST support the [Widgets-Packaging] specification and [DOM3Core].
Need to clarify dependency of HTML5's window object (or reference the Window spec). Need to talk to HTML-WG about having the spec moved outside of HTML5.
In addition to this specification, a user agent SHOULD support the following specifications:
The following definitions are used globally throughout this specification. Please note that other terms are given throughout this document and defined where they are used.
Widget object is presented to the user. When a user agent instantiates a start file, as defined by [Widgets-Packaging], the content of the
start file is said to be running in a widget context.Need to define what URI scheme we are going to use for widgets.
WindowWidget InterfaceObjects implementing [HTML5]'s Window interface MUST also implement the WindowWidget interface. The
WindowWidget interface provides access to [DOM3Core] Document objects in a
widget context.
interface WindowWidget {
readonly attribute Widget widget;
}
Widget AttributeThe read only widget attribute MUST contain a Widget
object.
Widget InterfaceWithin the widget context, the Widget
interface provides the following attributes and methods.
interface Widget {
readonly attribute dom::DOMString currentMode;
readonly attribute dom::DOMString locale;
readonly attribute dom::DOMString identifier;
readonly attribute WidgetIcon currentIcon;
readonly attribute dom::DOMString authorName;
readonly attribute dom::DOMString authorEmail;
readonly attribute dom::DOMString authorURL;
readonly attribute dom::DOMString name;
readonly attribute dom::DOMString description;
readonly attribute dom::DOMString version;
readonly attribute unsigned short width;
readonly attribute unsigned short height;
attribute Array preferences;
DOMString setPreference(in DOMString name, in DOMString value);
void getPreference(in DOMString name);
void hide();
void show();
attribute Function onmodechange;
attribute Function onbeforeupdate;
attribute Function onafterupdate;
boolean hasFeature(in DOMString url);
readonly attribute Array icons;
void setIcon(in DOMString url);
void setIcon(in WidgetIcon icon);
void openURL(DOMString url);
void getAttention();
void showNotification(in DOMString title, in DOMString message, in Function onclick);
}currentMode
AttributeThe currentMode attribute contains a representation of one valid window mode, as defined in [Widgets-Packaging]. Upon instantiation, this attribute MUST be set to the value of widget window mode, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
locale AttributeThe locale attribute represents the current locale for the running
widget. Upon instantiation, this attribute MUST be set to the value of widget locale, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
identifier AttributeThe identifier attribute represents a unique instance identifier for the widget. The instance
identifier MUST be unique on for each widget
instance on the device or machine it is installed.
Issue: how does an author access the widget's id as declared in the config document? Also, what happens if this is not unique? How is uniqueness assured?
currentIcon AttributeThe currentIcon attribute MUST contain a WidgetIcon object that represents the
current icon for the widget.
Issue: need to define how this icon is initially derived. This was in the Packaging spec, but no more. The above definition seems incomplete, what does "current" mean in this context.
authorName AttributeThe authorName attribute represents the name of the person who authored the widget. Upon instantiation, this attribute MUST be set to the value of author name, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
authorEmail AttributeThe authorEmail attribute represents an e-mail address associated with the author of a
widget. Upon instantiation, this attribute MUST be set to the value of author email, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
authorURL AttributeThe authorURL attribute represents a URI associated with the author of a
widget. Upon instantiation, this attribute MUST be set to the value of author href, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
name AttributeThe name attribute
represents the name of the widget. Upon instantiation, this attribute MUST be set to the value of widget name, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
Wondering if we should rename this widgetname to avoid confusion with window.name.
description AttributeThe description represents the description given to the widget. Upon instantiation, this attribute MUST be set to the value of widget description, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
version AttributeThe version attribute represents the version tag assigned to the widget. Upon instantiation, this attribute MUST be set to the value of widget version, which is derived from the Steps for Processing a Widget Resource in [Widgets-Packaging].
width Attribute
The width
Issue: need to define cases where the has been implicitly resized by the user agent, or explicitly resized by other means.
height Attribute
The height
Issue: need to define cases where the has been implicitly resized by the user agent, or explicitly resized by other means.
preferences AttributeThe preferences attribute holds either no preferences, or any preferences that have previously been stored
in the widget using the setPreference method.
The values held in preferences MUST be preserved across instantiations of the widget.
This feature is at Risk. We are still discussing if we should use HTML5's Storage to achieve this. Please send us feedback.
setPreference() MethodThe setPreference() method
accepts two arguments, both of which MUST be present. The first argument MUST be a DOMString providing the name of the preference to be stored. The
second argument MUST be
either a DOMString, or null.
When correctly invoked, the setPreference() method
MUST store the value from the second argument, in a preference with
the value from the first argument.
If setPreference()
is invoked with null as the second argument, and a preference
with the name from the first argument exists, the preference MUST be deleted.
If either argument to setPreference() is
invalid, a user agent MUST throw an
INVALID_ARGUMENT_ERR.
Issue: INVALID_ARGUMENT_ERR is not defined as extending DOM3Core's DOMException interface. Need to define it here or throw a predefined exception type.
This feature is at risk. We are still discussing if we should use HTML5's Storage to achieve this. Please send us feedback.
getPreference() MethodThe getPreference() method accepts one argument, a DOMString
containing the name of a preference to be retrieved from the preference
storage.
Upon invocation of the method, a user agent MUST attempt to retrieve the value of the preference with the
name given from the first argument, and return the value as a
DOMString. If a preference with the given name does not exist, the
user agent MUST instead return null.
hide() MethodIf the widget is visible, a user agent MAY hide the widget from the user's view. When a widget is hidden, it MUST stop accepting input events.
Issue: Does hiding change the window mode? Need to define "input event".
show() MethodUpon invocation of the method,
the show() the widget is visible, a user agent SHOULD ensure that if the widget is
invisible, should be made visible.
Issue: Does showing change the window mode or cause onmodechange to fire? This is under-defined. What happens if the widget is visible but off screen?
onmodechange CallbackThe onmodechange
attribute MAY hold a reference to a function that is to
be executed when a widget's view mode
changes, meaning that the value of the currentMode attribute
changes. Its initial value is null.
When a valid function is assigned to the attribute, a user agent MUST invoke this function whenever the view mode
has changed, without passing any arguments to the function. A conformant
implementation MUST further first set the value of the
currentMode attribute to the
new view mode prior to invoking the function.
onbeforeupdate CallbackThe onbeforeupdate
attribute MAY hold a reference to a function that is to
be executed before a widget is updated, prior to the widget shutting down to
prepare for the update. Its initial value is null.
When a user agent is about to update the widget update, the function assigned to this attribute is invoked prior to the widget instance shutting down, to allow the widget to perform a clean shutdown, and possibly prepare the widget for the next startup.
Should we add a checkForUpdate() method? which requests that the widget engine check if an update is available by using the Widget Update spec?
onafterupdate CallbackThe onafterupdate
attribute MAY hold a reference to a function that is to
be executed after a widget is updated. Its initial value is null.
On startup of a widget, the value of this attribute will always be null. If
the widget then assigns a function to this attribute, a user agent MUST immediately invoke the function after it has been assigned.
hasFeature() MethodThe hasFeature()
method accepts a valid DOMString as argument. This argument
represents a URI reference identifying an API. If this API is recognized and
available to the widget, the user agent MUST return
true. In all other cases, for example if the API not being recognized, or
access has been prohibited, the user agent MUST return false.
icons AttributeThe icons MUST hold an array of icon objects, each icon representing an
icon from the widget's manifest file.
setIcon() MethodThe setIcon method
accepts exactly one argument. This argument MUST be either
a a valid URI pointing to an image file inside the widget package,
or it must be a valid instance of a WidgetIcon object. When invoked, the
setIcon() method MAY change the application icon associated with the widget.
openURL() MethodThe openURL(url) method takes a
valid URI as argument. When invoked, the url should be opened in the default browser of the operating
system on which the widget runs. If there is no such browser or
the url is not a valid URI, then the user agent must act as if the method was not invoked.
getAttention() MethodWhen the getAttention() method is
invoked, a user agent MAY use a
system-specific method of alerting the user that the widget requires
attention. The user agent SHOULD NOT focus the widget.
This specification does not impose requirements for the user interface for
such a mechanism, but examples may include flashing a task-bar entry,
highlighting or animating the application icon for the widget.
showNotification() Method
The showNotification()
method accepts two arguments. The first argument is a
DOMString containing an informative message to be displayed to
the end-user. The second argument is an optional reference to a function
that is to be invoked if the user acknowledges the notification message, for
instance by clicking on it.
WidgetIcon interface
interface WidgetIcon {
readonly attribute DOMString src;
readonly attribute unsigned long width;
readonly attribute unsigned long height;
}
src Attribute The src attribute represents a valid URI to an image
file inside the widget package that represents an iconic representation of the widget.
width AttributeThe width represents the width of the icon in [CSS21] pixels.
height AttributeThe height represents the height of the icon in [CSS21] pixels.
This section will be completed as the document matures.