org.w3c.dom.events

Interface ProgressEvent

All Superinterfaces:

Event

public interface ProgressEvent
extends Event

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.

Note: This interface has not yet been accepted for inclusion in the W3C DOM 3 Event specification. It may be removed from the JSR 280 specification or added to a different namespace in a subsequent version of the specification.

Other specifications which have a use case for these events should define when ProgressEvent events are dispatched.

• The user agent must dispatch a start event when a relevant operation has begun.
• The user agent may dispatch one or more progress events while a network operation is taking place.
• If the operation fails to complete the user agent must dispatch either an 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).
• If the operation successfully completes, the user agent must dispatch a 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.

Event definitions

The following events are defined in this specification

Name	Description	How many?	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 successfully completed	never or once

These events must not bubble, and must not be cancelable.

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 initialization 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.

Field Summary

Fields inherited from interface org.w3c.dom.events.Event

AT_TARGET, BUBBLING_PHASE, CAPTURING_PHASE

Method Summary

Methods

Modifier and Type	Method and Description
boolean	getLengthComputable() Specifies whether the total size of the transfer is known.
int	getLoaded() Specifies the number of bytes downloaded since the beginning of the download.
int	getTotal() Specifies the expected total number of bytes of the content transferred in the operation.
void	initProgressEvent(String typeArg, boolean canBubbleArg, boolean cancelableArg, boolean lengthComputableArg, int loadedArg, int totalArg) The initProgressEvent method is used to initialize the value of a progress event created through the DocumentEvent interface.
void	initProgressEventNS(String namespaceURIArg, String typeArg, boolean canBubbleArg, boolean cancelableArg, boolean lengthComputableArg, int loadedArg, int totalArg) The initProgressEventNS method is used to initialize the value of a namespaced progress event created through the DocumentEvent interface.

Methods inherited from interface org.w3c.dom.events.Event

getBubbles, getCancelable, getCurrentTarget, getDefaultPrevented, getEventPhase, getNamespaceURI, getTarget, getTimeStamp, getType, initEvent, initEventNS, preventDefault, stopPropagation

Method Detail

getLengthComputable

boolean getLengthComputable()

Specifies whether the total size of the transfer is known.

getLoaded

int getLoaded()

Specifies the number of bytes downloaded since the beginning of the download. This refers to the content, excluding headers and overhead from the transaction, and where there is a content-encoding or transfer-encoding refers to the number of bytes to be transferred, i.e. with the relevant encodings applied. For more details on HTTP see [RFC2616].

getTotal

int getTotal()

Specifies the expected total number of bytes of the content transferred in the operation. Where the size of the transfer is for some reason unknown, the value of this attribute must be zero.

initProgressEvent

void initProgressEvent(String typeArg,
                     boolean canBubbleArg,
                     boolean cancelableArg,
                     boolean lengthComputableArg,
                     int loadedArg,
                     int totalArg)

The initProgressEvent method is used to initialize the value of a progress event created through the DocumentEvent interface. If this method is called multiple times, the final invocation takes precedence .

Parameters:

typeArg - This must be one of loadstart, progress, error, abort, load. If it is not one of those values then this specification does not define the resulting event.

canBubbleArg - This must be false. Where a value of true is passed, implementations must override that and change the value to false.

cancelableArg - This must be false. Where a value of true is passed, implementations must override that and change the value to false.

lengthComputableArg - If the implementation has reliable information about the value of total, then this should be true. If the implementation does not have reliable information about the value of total, this should be false.

loadedArg - Specifies the total number of bytes already loaded. If this value is not a non-negative number, the implementation must change it to zero.

totalArg - Specifies the total number of bytes to be loaded. If lengthComputable is false, this must be zero. If any other parameter is passed, and lengthComputable is false, the implementation must override this and set the value to zero. If lengthComputable is true, and the value of this parameter is not a non-negative number, the implementation must set lengthComputable to false and the value of total to zero.

initProgressEventNS

void initProgressEventNS(String namespaceURIArg,
                       String typeArg,
                       boolean canBubbleArg,
                       boolean cancelableArg,
                       boolean lengthComputableArg,
                       int loadedArg,
                       int totalArg)

The initProgressEventNS method is used to initialize the value of a namespaced progress event created through the DocumentEvent interface. This method may only be called before the progress event has been dispatched via the dispatchEvent method, though it may be called multiple times during that phase if necessary. If called multiple times, the final invocation takes precedence.

Parameters:

namespaceURIArg - Specifies the URI for the namespace of the event. For all events defined in this specification, the value of this parameter is null.

typeArg - This must be one of loadstart, progress, error, abort, load. If it is not one of those values then this specification does not define the resulting event.

canBubbleArg - This must be false. Where a value of true is passed, implementations must override that and change the value to false.

cancelableArg - This must be false. Where a value of true is passed, implementations must override that and change the value to false.

lengthComputableArg - If the implementation has reliable information about the value of total, then this should be true. If the implementation does not have reliable information about the value of total, this should be false.

loadedArg - This parameter specifies the total number of bytes already loaded. If this value is not a non-negative number, the implementation must change it to zero.

totalArg - This specifies the total number of bytes to be loaded. If lengthComputable is false, this must be zero. If any other parameter is passed, and lengthComputable is false, the implementation must override this and set the value to zero. If lengthComputable is true, and the value of this parameter is not a non-negative number, the implementation must set lengthComputable to false and the value of total to zero.