7.3 Timers

The setTimeout() and setInterval() methods allow authors to schedule timer-based callbacks.

[NoInterfaceObject]
interface WindowTimers {
  long setTimeout(Function handler, optional long timeout, any... arguments);
  long setTimeout(DOMString handler, optional long timeout, any... arguments);
  void clearTimeout(long handle);
  long setInterval(Function handler, optional long timeout, any... arguments);
  long setInterval(DOMString handler, optional long timeout, any... arguments);
  void clearInterval(long handle);
};
Window implements WindowTimers;

handle = window . setTimeout( handler [, timeout [, arguments... ] ] )

Schedules a timeout to run handler after timeout milliseconds. Any arguments are passed straight through to the handler.

handle = window . setTimeout( code [, timeout ] )

Schedules a timeout to compile and run code after timeout milliseconds.

window . clearTimeout( handle )

Cancels the timeout set with setTimeout() identified by handle.

handle = window . setInterval( handler [, timeout [, arguments... ] ] )

Schedules a timeout to run handler every timeout milliseconds. Any arguments are passed straight through to the handler.

handle = window . setInterval( code [, timeout ] )

Schedules a timeout to compile and run code every timeout milliseconds.

window . clearInterval( handle )

Cancels the timeout set with setInterval() identified by handle.

This API does not guarantee that timers will run exactly on schedule. Delays due to CPU load, other tasks, etc, are to be expected.

7.4 User prompts

7.4.1 Simple dialogs

window . alert(message)

Displays a modal alert with the given message, and waits for the user to dismiss it.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . confirm(message)

Displays a modal OK/Cancel prompt with the given message, waits for the user to dismiss it, and returns true if the user clicks OK and false if the user clicks Cancel.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

result = window . prompt(message [, default] )

Displays a modal text field prompt with the given message, waits for the user to dismiss it, and returns the value that the user entered. If the user cancels the prompt, then returns null instead. If the second argument is present, then the given value is used as a default.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

7.4.2 Printing

window . print()

Prompts the user to print the page.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

7.4.3 Dialogs implemented using separate documents

result = window . showModalDialog(url [, argument] )

Prompts the user with the given page, waits for that page to close, and returns the return value.

A call to the navigator.yieldForStorageUpdates() method is implied when this method is invoked.

[NoInterfaceObject] interface WindowModal {
  readonly attribute any dialogArguments;
           attribute DOMString returnValue;
};

window . dialogArguments

Returns the argument argument that was passed to the showModalDialog() method.

window . returnValue [ = value ]

Returns the current return value for the window.

Can be set, to change the value that will be returned by the showModalDialog() method.

The window.close() method can be used to close the browsing context.

7.5 System state and capabilities

7.5.1 The Navigator object

interface Navigator {
  // objects implementing this interface also implement the interfaces given below
};
Navigator implements NavigatorID;
Navigator implements NavigatorOnLine;
Navigator implements NavigatorContentUtils;
Navigator implements NavigatorStorageUtils;

7.5.1.1 Client identification

[NoInterfaceObject]
interface NavigatorID {
  readonly attribute DOMString appName;
  readonly attribute DOMString appVersion;
  readonly attribute DOMString platform;
  readonly attribute DOMString userAgent;
};

In certain cases, despite the best efforts of the entire industry, Web browsers have bugs and limitations that Web authors are forced to work around.

This section defines a collection of attributes that can be used to determine, from script, the kind of user agent in use, in order to work around these issues.

Client detection should always be limited to detecting known current versions; future versions and unknown versions should always be assumed to be fully compliant.

window . navigator . appName

Returns the name of the browser.

window . navigator . appVersion

Returns the version of the browser.

window . navigator . platform

Returns the name of the platform.

window . navigator . userAgent

Returns the complete User-Agent header.

7.5.1.2 Custom scheme and content handlers

[NoInterfaceObject]
interface NavigatorContentUtils {
  // content handler registration
  void registerProtocolHandler(DOMString scheme, DOMString url, DOMString title);
  void registerContentHandler(DOMString mimeType, DOMString url, DOMString title);
  DOMString isProtocolHandlerRegistered(DOMString scheme, DOMString url);
  DOMString isContentHandlerRegistered(DOMString mimeType, DOMString url);
  void unregisterProtocolHandler(DOMString scheme, DOMString url);
  void unregisterContentHandler(DOMString mimeType, DOMString url);
};

window . navigator . registerProtocolHandler(scheme, url, title)

window . navigator . registerContentHandler(mimeType, url, title)

Registers a handler for the given scheme or content type, at the given URL, with the given title.

The string "%s" in the URL is used as a placeholder for where to put the URL of the content to be handled.

Throws a SecurityError exception if the user agent blocks the registration (this might happen if trying to register as a handler for "http", for instance).

Throws a SyntaxError if the "%s" string is missing in the URL.

In addition to the registration methods, there are also methods for determining if particular handlers have been registered, and for unregistering handlers.

state = window . navigator . isProtocolHandlerRegistered(scheme, url)

state = window . navigator . isContentHandlerRegistered(mimeType, url)

Returns one of the following strings describing the state of the handler given by the arguments:

new

Indicates that no attempt has been made to register the given handler (or that the handler has been unregistered). It would be appropriate to promote the availability of the handler or to just automatically register the handler.

registered

Indicates that the given handler has been registered or that the site is blocked from registering the handler. Trying to register the handler again would have no effect.

declined

Indicates that the given handler has been offered but was rejected. Trying to register the handler again may prompt the user again.

state = window . navigator . unregisterProtocolHandler(scheme, url)

state = window . navigator . unregisterContentHandler(mimeType, url)

Unregisters the handler given by the arguments.

7.5.1.3 Manually releasing the storage mutex

[NoInterfaceObject]
interface NavigatorStorageUtils {
  void yieldForStorageUpdates();
};

window . navigator . yieldForStorageUpdates()

If a script uses the document.cookie API, or the localStorage API, the browser will block other scripts from accessing cookies or storage until the first script finishes. [WEBSTORAGE]

Calling the navigator.yieldForStorageUpdates() method tells the user agent to unblock any other scripts that may be blocked, even though the script hasn't returned.

Values of cookies and items in the Storage objects of localStorage attributes can change after calling this method, whence its name. [WEBSTORAGE]

7.5.2 The External interface

interface External {
  void AddSearchProvider(DOMString engineURL);
  unsigned long IsSearchProviderInstalled(DOMString engineURL);
};

window . external . AddSearchProvider( url )

Adds the search engine described by the OpenSearch description document at url. [OPENSEARCH]

The OpenSearch description document has to be on the same server as the script that calls this method.

installed = window . external . IsSearchProviderInstalled( url )

Returns a value based on comparing url to the URLs of the results pages of the installed search engines.

0

None of the installed search engines match url.

1

One or more installed search engines match url, but none are the user's default search engine.

2

The user's default search engine matches url.

The url is compared to the URLs of the results pages of the installed search engines using a prefix match. Only results pages on the same domain as the script that calls this method are checked.

Another way of exposing search engines using OpenSearch description documents is using a link element with the search link type.

7.6 Images

interface ImageBitmap {
  // opaque object
};

callback ImageBitmapCallback = void (ImageBitmap image);

[NoInterfaceObject]
interface ImageBitmapFactories {
  void createImageBitmap(HTMLImageElement image, ImageBitmapCallback _callback);
  void createImageBitmap(HTMLVideoElement image, ImageBitmapCallback _callback);
  void createImageBitmap(HTMLCanvasElement image, ImageBitmapCallback _callback); 
  void createImageBitmap(Blob image, ImageBitmapCallback _callback);
  void createImageBitmap(ImageData image, ImageBitmapCallback _callback); 
  void createImageBitmap(CanvasRenderingContext2D image, ImageBitmapCallback _callback); 
};
Window implements ImageBitmapFactories;
WorkerUtils implements ImageBitmapFactories;

An ImageBitmap object represents a bitmap image that can be painted to a canvas without undue latency.

The exact judgement of what is undue latency of this is left up to the implementer, but in general if making use of the bitmap requires network I/O, or even local disk I/O, then the latency is probably undue; whereas if it only requires a blocking read from a GPU or system RAM, the latency is probably acceptable.

Window . createImageBitmap(image, callback)

Takes image, which can be an img element, video, or canvas element, a Blob object, an ImageData object, or a CanvasRenderingContext2D object, and asynchronously calls callback with a new ImageBitmap as its argument when it has created one.

If no ImageBitmap object can be constructed, for example because the provided image data is not actually an image, then the callback is invoked with null as the value instead.

Throws an InvalidStateError exception if the source image is not in a valid state (e.g. an img element that hasn't finished loading, or a CanvasRenderingContext2D object whose bitmap data has zero length along one or both dimensions). Throws a SecurityError exception if the script is not allowed to access the image data of the source image (e.g. a video that is CORS-cross-origin, or a canvas being drawn on by a script in a worker from another origin).