8.4 Timers

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

[NoInterfaceObject, Exposed=Window,Worker]
interface WindowTimers {
  long setTimeout(Function handler, optional long timeout = 0, any... arguments);
  long setTimeout(DOMString handler, optional long timeout = 0, any... arguments);
  void clearTimeout(optional long handle = 0);
  long setInterval(Function handler, optional long timeout = 0, any... arguments);
  long setInterval(DOMString handler, optional long timeout = 0, any... arguments);
  void clearInterval(optional long handle = 0);
};
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.

Timers can be nested; after five such nested timers, however, the interval is forced to be at least four milliseconds.

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

To run tasks of several milliseconds back to back without any delay, while still yielding back to the browser to avoid starving the user interface (and to avoid the browser killing the script for hogging the CPU), simply queue the next timer before performing work:

function doExpensiveWork() {
  var done = false;
  // ...
  // this part of the function takes up to five milliseconds
  // set done to true if we're done
  // ...
  return done;
}

function rescheduleWork() {
  var handle = setTimeout(rescheduleWork, 0); // preschedule next iteration
  if (doExpensiveWork())
    clearTimeout(handle); // clear the timeout if we don't need it
}

function scheduleWork() {
  setTimeout(rescheduleWork, 0);
}

scheduleWork(); // queues a task to do lots of work

8.5 User prompts

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

Logic that depends on tasks or microtasks, such as media elements loading their media data, are stalled when these methods are invoked.

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

8.5.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 any 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.

8.6 System state and capabilities

8.6.1 The Navigator object

interface Navigator {
  // objects implementing this interface also implement the interfaces given below
};
Navigator implements NavigatorID;
Navigator implements NavigatorLanguage;
Navigator implements NavigatorOnLine;
Navigator implements NavigatorContentUtils;
Navigator implements NavigatorStorageUtils;
Navigator implements NavigatorPlugins;
8.6.1.1 Client identification
[NoInterfaceObject, Exposed=Window,Worker]
interface NavigatorID {
  readonly attribute DOMString appCodeName; // constant "Mozilla"
  readonly attribute DOMString appName;
  readonly attribute DOMString appVersion;
  readonly attribute DOMString platform;
  readonly attribute DOMString product; // constant "Gecko"
  boolean taintEnabled(); // constant false
  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 . appCodeName

Returns the string "Mozilla".

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

Returns the string "Gecko".

window . navigator . taintEnabled()

Returns false.

window . navigator . userAgent

Returns the complete User-Agent header.

8.6.1.2 Language preferences
[NoInterfaceObject, Exposed=Window,Worker]
interface NavigatorLanguage {
  readonly attribute DOMString? language;
  readonly attribute DOMString[] languages;
};
window . navigator . language

Returns a language tag representing the user's preferred language.

window . navigator . languages

Returns an array of language tags representing the user's preferred languages, with the most preferred language first.

The most preferred language is the one returned by navigator.language.

A languagechange event is fired at the Window or WorkerGlobalScope object when the user agent's understanding of what the user's preferred languages are changes.

8.6.1.3 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);
};

The registerProtocolHandler() method allows Web sites to register themselves as possible handlers for particular schemes. For example, an online telephone messaging service could register itself as a handler of the sms: scheme, so that if the user clicks on such a link, he is given the opportunity to use that Web site. Analogously, the registerContentHandler() method allows Web sites to register themselves as possible handlers for content in a particular MIME type. For example, the same online telephone messaging service could register itself as a handler for text/vcard files, so that if the user has no native application capable of handling vCards, his Web browser can instead suggest he use that site to view contact information stored on vCards that he opens. [RFC5724] [RFC6350]

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

8.6.1.4 Manually releasing the storage mutex
[NoInterfaceObject]
interface NavigatorStorageUtils {
  readonly attribute boolean cookieEnabled;
  void yieldForStorageUpdates();
};
window . navigator . cookieEnabled

Returns false if setting a cookie will be ignored, and true otherwise.

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]

8.6.1.5 Plugins
[NoInterfaceObject]
interface NavigatorPlugins {
  readonly attribute PluginArray plugins;
  readonly attribute MimeTypeArray mimeTypes;
  readonly attribute boolean javaEnabled;
};

interface PluginArray {
  void refresh(optional boolean reload = false);
  readonly attribute unsigned long length;
  getter Plugin? item(unsigned long index);
  getter Plugin? namedItem(DOMString name);
};

interface MimeTypeArray {
  readonly attribute unsigned long length;
  getter MimeType? item(unsigned long index);
  getter MimeType? namedItem(DOMString name);
};

interface Plugin {
  readonly attribute DOMString name;
  readonly attribute DOMString description;
  readonly attribute DOMString filename;
  readonly attribute unsigned long length;
  getter MimeType? item(unsigned long index);
  getter MimeType? namedItem(DOMString name);
};

interface MimeType {
  readonly attribute DOMString type;
  readonly attribute DOMString description;
  readonly attribute DOMString suffixes; // comma-separated
  readonly attribute Plugin enabledPlugin;
};
window . navigator . plugins . refresh( [ refresh ] )

Updates the lists of supported plugins and MIME types for this page, and reloads the page if the lists have changed.

window . navigator . plugins . length

Returns the number of plugins, represented by Plugin objects, that the user agent reports.

plugin = window . navigator . plugins . item(index)
window . navigator . plugins[index]

Returns the specified Plugin object.

plugin = window . navigator . plugins . item(name)
window . navigator . plugins[name]

Returns the Plugin object for the plugin with the given name.

window . navigator . mimeTypes . length

Returns the number of MIME types, represented by MimeType objects, supported by the plugins that the user agent reports.

mimeType = window . navigator . mimeTypes . item(index)
window . navigator . mimeTypes[index]

Returns the specified MimeType object.

mimeType = window . navigator . mimeTypes . item(name)
window . navigator . mimeTypes[name]

Returns the MimeType object for the given MIME type.

plugin . name

Returns the plugin's name.

plugin . description

Returns the plugin's description.

plugin . filename

Returns the plugin library's filename, if applicable on the current platform.

plugin . length

Returns the number of MIME types, represented by MimeType objects, supported by the plugin.

mimeType = plugin . item(index)
plugin[index]

Returns the specified MimeType object.

mimeType = plugin . item(name)
plugin[name]

Returns the MimeType object for the given MIME type.

mimeType . type

Returns the MIME type.

mimeType . description

Returns the MIME type's description.

mimeType . suffixes

Returns the MIME type's typical file extensions, in a comma-separated list.

mimeType . enabledPlugin

Returns the Plugin object that implements this MIME type.

window . navigator . javaEnabled

Returns true if there's a plugin that supports the MIME type "application/x-java-vm".

8.6.2 The External interface

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

For historical reasons, members on this interface are capitalized.

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.

8.7 Images

[Exposed=Window,Worker]
interface ImageBitmap {
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
};

typedef (HTMLImageElement or
         HTMLVideoElement or
         HTMLCanvasElement or
         Blob or
         ImageData or
         CanvasRenderingContext2D or
         ImageBitmap) ImageBitmapSource;

[NoInterfaceObject, Exposed=Window,Worker]
interface ImageBitmapFactories {
  Promise createImageBitmap(ImageBitmapSource image, optional long sx, long sy, long sw, long sh);
};
Window implements ImageBitmapFactories;
WorkerGlobalScope 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.

promise = Window . createImageBitmap(image [, sx, sy, sw, sh ] )

Takes image, which can be an img element, video, or canvas element, a Blob object, an ImageData object, a CanvasRenderingContext2D object, or another ImageBitmap object, and returns a Promise that is resolved when a new ImageBitmap is created.

If no ImageBitmap object can be constructed, for example because the provided image data is not actually an image, then the promise is rejected instead.

If sx, sy, sw, and sh arguments are provided, the source image is cropped to the given pixels, with any pixels missing in the original replaced by transparent black. These coordinates are in the source image's pixel coordinate space, not in CSS pixels.

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, or an ImageData object whose data is data attribute has been neutered). 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).

imageBitmap . width

Returns the intrinsic width of the image, in CSS pixels.

imageBitmap . height

Returns the intrinsic height of the image, in CSS pixels.

Using this API, a sprite sheet can be precut and prepared:

var sprites = {};
function loadMySprites() {
  var image = new Image();
  image.src = 'mysprites.png';
  var resolver;
  var promise = new Promise(function (arg) { resolver = arg });
  image.onload = function () {
    resolver.resolve(Promise.every(
      createImageBitmap(image,  0,  0, 40, 40).then(function (image) { sprites.woman = image }),
      createImageBitmap(image, 40,  0, 40, 40).then(function (image) { sprites.man   = image }),
      createImageBitmap(image, 80,  0, 40, 40).then(function (image) { sprites.tree  = image }),
      createImageBitmap(image,  0, 40, 40, 40).then(function (image) { sprites.hut   = image }),
      createImageBitmap(image, 40, 40, 40, 40).then(function (image) { sprites.apple = image }),
      createImageBitmap(image, 80, 40, 40, 40).then(function (image) { sprites.snake = image }),
    ));
  };
  return promise;
}

function runDemo() {
  var canvas = document.querySelector('canvas#demo');
  var context = canvas.getContext('2d');
  context.drawImage(sprites.tree, 30, 10);
  context.drawImage(sprites.snake, 70, 10);
}

loadMySprites().then(runDemo);