Fullscreen

Abstract

Fullscreen defines the fullscreen API for the web platform.

Table of Contents

1. 1 Conformance
2. 2 Terminology
3. 3 Model
4. 4 API
5. 5 UI
6. 6 Rendering
   1. 6.1 New stacking layer
   2. 6.2 ::backdrop pseudo-element
   3. 6.3 :fullscreen pseudo-class
   4. 6.4 User-agent level style sheet defaults
7. 7 Security and Privacy Considerations
8. References
9. Acknowledgments

1 Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

2 Terminology

Most terminology used in this specification is from CSS, DOM, and HTML. [CSS] [DOM] [HTML5]

The term context object means the object on which the method or attribute being discussed was called. When the context object is unambiguous, the term can be omitted.

A browsing context A is called a descendant browsing context of a browsing context B if and only if B is an ancestor browsing context of A.

3 Model

The task source used by this specification is the user interaction task source.

All documents have an associated fullscreen enabled flag and fullscreen element stack. Unless otherwise stated the fullscreen enabled flag is unset and the fullscreen element stack is empty.

HTML defines under what conditions the fullscreen enabled flag is set. [HTML]

To add an element on a document's fullscreen element stack, add it on top of document's browsing context's top layer, and then add it on top of document's fullscreen element stack.

To remove an element from a document's fullscreen element stack, remove it from document's browsing context's top layer, and then remove it from document's fullscreen element stack.

To empty a document's fullscreen element stack, remove all the elements in it from document's browsing context's top layer, and then empty document's fullscreen element stack.

To fully exit fullscreen act as if the exitFullscreen() method was invoked on the top-level browsing context's document and subsequently empty that document's fullscreen element stack.

Since a fullscreenchange event will be dispatched regardless, emptying the fullscreen element stack per above is fine.

If an element at the top of a fullscreen element stack is removed from a document, fully exit fullscreen.

4 API

partial interface Element {
  void requestFullscreen();
};

partial interface Document {
  readonly attribute boolean fullscreenEnabled;
  readonly attribute Element? fullscreenElement;

  void exitFullscreen();
};

element . requestFullscreen()

Displays element fullscreen.

document . fullscreenEnabled

Returns true if document has the ability to display elements fullscreen, or false otherwise.

document . fullscreenElement

Returns the element that is displayed fullscreen, or null if there is no such element.

document . exitFullscreen()

Stops any elements within document from being displayed fullscreen.

The requestFullscreen() method must run these steps:

1. If any of the following conditions are true, queue a task to fire an event named fullscreenerror with its bubbles attribute set to true on the context object's node document, and then terminate these steps:

   • The context object is not in a document.

   • The context object's node document, or an ancestor browsing context's document does not have the fullscreen enabled flag set.

   • The context object's node document fullscreen element stack is not empty and its top element is not an ancestor of the context object.

   • A descendant browsing context's document has a non-empty fullscreen element stack.

   • This algorithm is not allowed to show a pop-up.

   • There is a previously-established user preference, security risk, or platform limitation.

2. Return, and run the remaining steps asynchronously.

3. Optionally, perform some animation.

4. Let doc be element's node document.

5. Let docs be all doc's ancestor browsing context's documents (if any) and doc, in order of furthest away from doc to doc.

6. For each document in docs, run these substeps:

   1. Let following document be the document after document in docs, or null if there is no such document.

   2. If following document is null, queue a task to add context object on document's fullscreen element stack and fire an event named fullscreenchange with its bubbles attribute set to true on the document.

   3. Otherwise, if document's fullscreen element stack is either empty or its top element is not following document's browsing context container, queue a task to add following document's browsing context container on document's fullscreen element stack and fire an event named fullscreenchange with its bubbles attribute set to true on document.

   4. Otherwise, do nothing for this document. It stays the same.

7. Optionally, display a message indicating how the user can exit displaying the context object fullscreen.

The fullscreenEnabled attribute must return true if the context object and all ancestor browsing context's documents have their fullscreen enabled flag set, or false otherwise.

The fullscreenElement attribute must return the top element of the context object's fullscreen element stack, or null otherwise.

The exitFullscreen() method must run these steps:

1. Let doc be the context object.

2. If doc's fullscreen element stack is empty, terminate these steps.

3. Return, and run the remaining steps asynchronously.

4. Optionally, perform some animation.

5. Let descendants be all the doc's descendant browsing context's documents with a non-empty fullscreen element stack (if any), ordered so that the child of the doc is last and the document furthest away from the doc is first.

6. For each descendant in descendants, queue a task to empty descendant's fullscreen element stack and fire an event named fullscreenchange with its bubbles attribute set to true on descendant.

7. While doc is not null, run these substeps:

   1. Remove the top element of doc's fullscreen element stack.

      If doc's fullscreen element stack is non-empty and the element now at the top is either not in a document or its node document is not doc, run these substeps again.

      This is needed because a non-top element in the fullscreen element stack could have been removed from doc.

   2. Queue a task to fire an event named fullscreenchange with its bubbles attribute set to true on doc.

   3. If doc's fullscreen element stack is empty and doc's browsing context has a browsing context container, set doc to that browsing context container's node document.

   4. Otherwise, set doc to null.

5 UI

User agents are encouraged to implement native media fullscreen controls in terms of requestFullscreen() and exitFullscreen().

If the end user instructs the user agent to end a fullscreen session initiated via requestFullscreen(), fully exit fullscreen.

6 Rendering

This section is to be interpreted equivalently to the Rendering section of HTML. [HTML]

6.1 New stacking layer

This specification introduces a new stacking layer to the Elaborate description of Stacking Contexts of CSS 2.1. It is called the top layer, comes after step 10 in the painting order, and is therefore rendered closest to the user within a viewport. Each browsing context has one associated viewport and therefore also one top layer. [CSS]

The terminology used in this and following subsection attempts to match CSS 2.1 Appendix E.

The top layer consists of a stack of elements, rendered in the order they have been added to the stack. The last element added to the stack is rendered closest to the user.

The z-index property has no effect in the top layer.

An element in this stack has the following attributes:

• It generates a new stacking context.

• Its parent stacking context is the root stacking context.

• Its containing block is the initial containing block.

• It is rendered as an atomic unit as if it were a sibling of the root element.

  Ancestor elements with overflow, opacity, masks, etc. cannot affect it.

• It is not rendered if it, or an ancestor, has the display property set to none.

• If its specified position property is static, it computes to absolute.

• Its outline, if any, is to be rendered before step 10 in the painting order.

• Unless overridden by another specification, its static position for left, right, and top is zero.

6.2 ::backdrop pseudo-element

Each element in the top layer's stack has a ::backdrop pseudo-element. This pseudo-element is a box rendered immediately below the element (and above the element below the element in the stack, if any), within the same top layer.

The ::backdrop pseudo-element can be used to create a backdrop that hides the underlying document for an element in the top layer's stack. E.g. for the element that is displayed fullscreen as described by this specification.

It does not inherit from any element and is not inherited from. No restrictions are made on what properties apply to this pseudo-element either.

6.3 :fullscreen pseudo-class

The :fullscreen pseudo-class must match the top element of the document's fullscreen element stack (if any).

6.4 User-agent level style sheet defaults

@namespace "http://www.w3.org/1999/xhtml";

*|*:fullscreen {
  position:fixed;
  top:0; right:0; bottom:0; left:0;
  margin:0;
  box-sizing:border-box;
  width:100%;
  height:100%;
  object-fit:contain;
}

iframe:fullscreen {
  border:none;
}

*|*:fullscreen::backdrop {
  position:fixed;
  top:0; right:0; bottom:0; left:0;
  background:black;
}

7 Security and Privacy Considerations

User agents should ensure, e.g. by means of an overlay, that the end user is aware something is displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and advertise this to the user. This is to prevent a site from spoofing the end user by recreating the user agent or even operating system environment when fullscreen. See also the definition of requestFullscreen().

To prevent embedded content from going fullscreen only embedded content specifically allowed via the allowfullscreen attribute of the HTML iframe element will be able to go fullscreen. This prevents untrusted content from going fullscreen.

References

Acknowledgments

Many thanks to Robert O'Callahan for designing the initial model and being awesome.

Thanks to Chris Pearce, Darin Fisher, Edward O'Connor, fantasai, Glenn Maynard, Ian Hickson, João Eiras, Josh Soref, Øyvind Stenhaug, Rafał Chłodnicki, Rune Lillesveen, Sigbjørn Vik, Simon Pieters, and Tab Atkins for also being awesome.