Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document describes event types that can be used for monitoring the progress of an operation. It is primarily intended for contexts such as data transfer operations specified by XMLHTTPRequest [XHR], or Media Access Events [MAE].
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/.
This document is an editor's draft specification of the ProgressEvent events from the Web API group, part of the Rich Web Client Activity. It defines events which can be used to monitor a process and provide feedback to a user, particularly for network-based events. This editor's draft does not imply any consensus of or endorsement by any member of the working group, and may contain minor or major errors.
This version is published as a draft replacement for the first public W3C Working Draft and incorporates some comments received about that draft. All comments are welcome and may be sent to public-webapi@w3.org. All messages received at this address are viewable in a public archive. If the outstanding issues identified in this draft, and any raised by review, can be resolved in time, this specification will hopefully be published as a Last Call Working draft by the end of 2007. Currently there are several known issues which are unresolved by this specification. These may be identified in the draft thus:@@issue: Something that needs to be settled before the draft is ready for LC, or logged in the WebAPI group's issue tracker for the ProgressEvents (Member-only). Ideally they will be noted in the draft with a link to the tracker, but that is not always the case.
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.
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.
The terms must, should, may, must not, should not, are used in this document in accordance with [RFC2119]. A conformant implementation of this specification meets all relevant requirements identified by the use of these terms.
There are three classes of conformance to this specification:
ProgressEvent
eventsThe following events are defined in this specification
Name | Description | How often? | When? |
---|---|---|---|
loadstart |
The operation has begun | once | Must be dispatched first |
progress |
The operation is in progress | zero or more | May be dispatched zero or more times after a loadstart
event, before any of error, abort or load events are dispatched |
error |
The operation failed to complete, e.g. as a result of a network error | never or once | Exactly one of these must be dispatched |
abort |
The operation was cancelled, e.g. as a result of user interaction | never or once | |
load |
The operation successfuly completed | never or once |
@@ISSUE-117: Should
there be a stalled
event?
These events must not bubble, and must not be cancelable. @@ISSUE-118: Should it be possible to override this in the initialisation?
These events trigger event listeners attached on Element
nodes for that event and on the capture and target phases.
No default action is defined for these events.
These events are in the null namespace. Two kinds of initialisation methods are provided: one in which the namespace is required (and must be null) and one which assigns the null namespace automatically, This specification does not recommend use of one method over the other, and authors may choose whichever method suits them better for any given usage.
Where this specification repeats information from the DOM Level 3 Events specification [D3E], the repeated information in this section is informative. In the case of any conflict between the specifications the DOM Level 3 Events specification is normative.
interface ProgressEvent : events::Event { readonly attribute boolean lengthComputable; readonly attribute unsigned long loaded; readonly attribute unsigned long total; void initProgressEvent(in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in boolean lengthComputableArg, in unsigned long loadedArg, in unsigned long totalArg, void initProgressEventNS(in DOMString namespaceURI, in DOMString typeArg, in boolean canBubbleArg, in boolean cancelableArg, in boolean lengthComputableArg, in unsigned long loadedArg, in unsigned long totalArg, };
lengthComputable
loaded
total
Event.initEventNS()
, where the value of the
namespace parameter is specified as null
[D3E].
Event.initEvent()
method [D3E] for further
description of this parameter.Event.initEventNS()
[D3E]. Except
as described below, parameters are the same as for initProgressEvent.
A progress event occurs when the user agent makes progress in some data transfer operation, such as loading a resource from the web via XMLHttpRequest [XHR]. Specifications which have a use case for these events should define when Progress events are dispatched.
start
event when a
relevant operation has begun. progress
events while a network operation is taking
place.error
event, if the failure to complete
was due to an error (such as a timeout, or network error), or an
abort
event if the operation was deliberately cancelled
(e.g. by user interaction or through a script call).load
event. In short, there must be at least one start
event, followed by
zero or more progress
events, followed by one event which may be
any of error
, abort
or load
, according
to the outcome of the operation.
This example is informative and does not necessarily illustrate best practice.
FooAPI has a sendAndRetrieve()
method, which sends some
content via a predefined SMTP server and retrieves some other content via
HTTP HEAD from a URI given as a parameter. It specifies two event targets
send
and receive
. Progress events as specified in
the ProgressEvent events specification may be dispatched on these targets for
the send and receive phases respectively. If any progress events are
dispatched, then at least one start
event, and one of
error
, abort
, or load
must be
dispatched on each target. For the send phase, the total
attribute of the progress events measures the size of the RFC822 message
body. For the receive phase, the total attribute specifies the size of the
content to be returned in the HTTP HEAD operation.
Scripts may use progress events in order to provide feedback on operations performed by an application.
progress
event an SVG
document. In this example, the application uses the information in progress events emitted as an image loads in order to fill a progress bar as it receives progress events. Where the size of a download is unknown there is simply an block moving back and forth within the progress bar to indicate that there is still some kind of activity.
<svg xmlns="http://www.w3.org/2000/svg" version="1.1"
xmlns:xlink="http://www.w3.org/1999/xlink"
viewBox="0 0 400 400">
<script type="application/ecmascript"><![CDATA[
var xlinkNS = "http://www.w3.org/1999/xlink"
function showImage(imageHref) {
var image = document.getElementById('myImage');
image.setAttributeNS(xlinkNS, "href", imageHref);
image.addEventListener("progress",imageLoadProgress,false);
image.addEventListener("load",imageLoadComplete,false);
}
function imageLoadProgress(evt) {
if (evt.lengthComputable && evt.total != 0) { // we know the size, don't divide by zero
var progressBar = document.getElementById('progressBar');
progressBar.setAttribute("width", 100*evt.loaded/evt.total);
var loadAnimation = document.getElementById('loadAnimation');
loadAnimation.endElement();
} else { // we don't know the size and we need not to divide by zero
var progressBar = document.getElementById('progressBar');
progressBar.setAttribute("width", 20);
var loadAnimation = document.getElementById('loadAnimation');
loadAnimation.beginElement();
}
}
function imageLoadComplete(evt) {
var progressBar = document.getElementById('progressBar');
progressBar.setAttribute("width", 100);
var loadAnimation = document.getElementById('loadAnimation');
loadAnimation.endElement();
}
]]></script>
<image id="myImage" xlink:href="imageA.png" width="300" height="400"/>
<rect onclick="showImage('imageB.png')" width="120"
height="30" y="400" id="button" />
<animate id="loadAnimation" xlink:href="#progressBar" attributeName="x"
by="80" dur="1s" begin="button.click" repeatCount="indefinite"/>
<g id="meter" opacity="0">
<set attributeName="opacity" to=".7" begin="button.click" end="myImage.load"/>
<rect width="101" fill="none" height="5" x="5" y="5" stroke-width="1"/>
<rect id="progressBar" fill="#444" height="4" x="5.5" y="5.5"/>
</g>
</svg>
progress
events.Element
nodeslengthComputable
back to IDL definitions
toolengthComputable
backtotal
and
loaded
preload
and postload
event
types, added uploadprogress
lengthComputable
attributetotal
as zero if it is
unknownVarious editorial changes and corrections and modifications to the examples are made from draft to draft. These are not noted in the change history.
progress
element
proposed by WHAT-WGThe editor would like to thank the SVG working group for producing the
draft [SVGD] that this was initially based on. The
WHATWG's proposed progress
element [WPE] and
the documentation for Internet Explorer's onProgress
implementation [IEoP] were also useful as an initial
reference for this specification. In addition, the following individuals'
comments have been invaluable in preparing this draft:
Robin Berjon, Jean-Yves Bitterlich, Marcos Caceres, Suresh Chitturi, Alex Danilo, Erik Dahlstr�m, Jean-Claude Duford, Andrew Emmons, Jo�o Eiras, Gorm Eriksen, Ian Hickson, Bjoern Hoehrmann, Bj�rn Hoehrmann, David H�s�ther, Bj�rn H�hrmann, Bjoern H�hrmann, Anne van Kesteren, Travis Leithead, Aaron Leventhal, Jim Ley, Chrus Lilley, Cameron McCormack, Michael Antony Puls, Nandini Ramani, Robert Sayre, Alan Schepers, Doug Schepers, Rich Schwerdtfeger, Lisa Seeman, Andrew Shellshear, Ellen Siegel, Andy Sledd, Maciej Stachowiak, Boris Zbarsky, Gottfried Zimmermann
The editor apologises to anyone who has inadvertently been left off this list, and welcomes corrections.