Gecko:FullScreenAPI

Requirements

• Scripts should be able to initiate and terminate fullscreen
  • Allows custom, in-page, discoverable UI to active fullscreen
• Arbitrary Web content should be visible fullscreen
  • <video>, <canvas>, multicolumn text, etc
  • Required for scripted video controls
• Entering and exiting fullscreen must trigger events
  • To allow scripted changes to content, e.g. resizing of canvas content
• Scripts should be able to opt in to having alphanumeric keyboard input disabled during fullscreen
  • Enables less restrictive anti-spoofing measures
• Actual fullscreen transitions must be allowed to be asynchronous and entirely at the discretion of the UA
  • To enable passive notification/confirmation UI
  • To enable a wide range of security measures to prevent spoofing or other abuse

• Making a single element fullscreen should be as simple as possible

• Content in IFRAMEs should be able go fullscreen
  • To enable "widgets" such as embedded videos to offer fullscreen UI

Proposed Specification

A Document can be in the "fullscreen state". What exactly this means is up to the UA, but typically it means that the Document covers most or all of the screen and some or all of the normal UA UI is not visible.

It is possible for non-toplevel browsing contexts to have their Document in the fullscreen state. The parent browsing context of a browsing context with its Document in the fullscreen state must also have its Document in the fullscreen state.

The user agent may transition a Document into or out of the fullscreen state at any time, whether or not script has requested it. User agents are encouraged to provide standard UI to exit the fullscreen state, for example if the user presses the Escape key.

Toplevel browsing contexts can be in a "keys disabled" state. In this state, the user agent must suppress all keyup, keydown and keypress events whose keyCode is not in one of the following ranges:

• DOM_VK_CANCEL to DOM_VK_CAPS_LOCK, inclusive
• DOM_VK_SPACE to DOM_VK_DELETE, inclusive
• DOM_VK_SEMICOLON to DOM_VK_EQUALS, inclusive
• DOM_VK_MULTIPLY to DOM_VK_META, inclusive

Such events are not dispatched to any nodes in any document of the toplevel browsing context or descendant browsing contexts. This includes suppression of any internal key event processing that would insert text into form controls or editable content. The user agent might respond to such events by leaving fullscreen mode.

Each document has an optional "current fullscreen element".

New method of Document:

• void cancelFullScreen()

Requests that the UA exit fullscreen mode. The UA is not required to honor this, for example the UA might require that only a Document that last triggered fullscreen can cancel it.

The current fullscreen element for the document is cleared.

New methods of Element:

• void requestFullScreen()

The current fullscreen element for the document is set to this element.

Typically the user agent would react by transitioning the Document to the fullscreen state, or by presenting asynchronous confirmation UI and transitioning to the fullscreen state if/when the user responds affirmatively. However, the user agent is not required to do anything at all in response to requestFullScreen. The user agent's behavior is allowed to vary depending on whether requestFullScreen is called during a user event (e.g. a mouse click handler).

• void requestFullScreenWithKeys()

As requestFullScreen, but hints to the UA that while in fullscreen state, the toplevel browsing context for this Document should have keys disabled. While keys are disabled, there may be a reduced risk of spoofing attacks inducing the user to input inappropriate data, and the UA may choose to relax restrictions on entering fullscreen state with keys disabled.

New DOM attribute of Document:

• readonly attribute boolean fullScreen

Returns true while the document is in the fullscreen state.

• readonly attribute boolean fullScreenKeyboardInputAllowed

Returns true while the window's toplevel browsing context is fullscreen and not in a "keys disabled" state.

New content attribute of the <iframe> element:

• allowfullscreen

This is a boolean attribute. When this attribute is not set, UAs must ignore fullscreen requests in the iframe or its descendant frames.

New events:

• fullscreenchange

When a Document enters or leaves the fullscreen state, the user agent must queue a task to dispatch this event. When the event is dispatched, if the document's current fullscreen element is an element in the document, then the event target is that element, otherwise the event target is the document. The event bubbles and is not cancellable.

The 'onfullscreenchange' event handling attribute is supported on HTML elements.

New CSS psuedoclass:

• :full-screen

While a Document is in the fullscreen state, and the document's current fullscreen element is an element in the document, the 'full-screen' pseudoclass applies to that element. Also, an <iframe>, <object> or <embed> element whose child browsing context's Document is in the fullscreen state has the 'full-screen' pseudoclass applied.

New CSS media query selector:

• full-screen

that accepts two states:

• on
• off

While a Document is in the fullscreen state, the fullscreen media type is active for the document.

Suggested UA stylesheet rule:

/* A fullscreen element that is not the root element should be stretched
   to cover the viewport. */
:full-screen:not(:root) {
  position:fixed;
  top:0;
  left:0;
  right:0;
  bottom:0;
  z-index:2147483647;
  background:black;
}
/* In fullscreen mode, if the root element itself is not fullscreen then
   we should hide the viewport scrollbar. */
@media all and (full-screen:on) {
  :root:not(:full-screen) {
    overflow:hidden;
  }
}

Note that it is possible for a document to position content over an element with the :full-screen pseudo-class, for example if the :full-screen element is in a container with z-index not 'auto'.

Suggested UA Policy

The specification intentionally gives UAs great freedom in policy, because no one policy can fit all users, devices, and user interface designs. However, here is a policy that should be acceptable for conventional desktop browsers.

• requestFullScreen while the window is already in the fullscreen state is approved.
• Otherwise, requestFullScreen outside a user action (e.g. a non-synthesized input event handler) is denied.
• Otherwise, requestFullScreen without the ALLOW_KEYBOARD_INPUT flag is approved.
• Otherwise, passive confirmation UI is presented and requestFullScreen is approved if and when the user approves it.

Implications

There is no requirement to exit fullscreen state when a browsing context is navigated to a new page.

There is no requirement to exit fullscreen state if the current fullscreen element shifts to another element, or ceases to be an element in the document (e.g. because requestFullScreen was called again in the document or in some descendant document, or because the element is removed).

Nothing in this specification depends on whether the current fullscreen element is visible (e.g. whether it has "display:none").

Nothing in this specification affects or depends on focus.

Examples

1. Make a video element display fullscreen when clicked and leave fullscreen when it ends.

<video src="pelican.webm" autoplay
       onclick="event.target.requestFullScreen()"
       onended="document.cancelFullScreen()">
</video>

2. Make a canvas element display fullscreen in response to user input. Resize the canvas to the appropriate resolution while it's fullscreen.

<script>
function redrawCanvas(c) { ... }
function resizeCanvas() {
  var c = document.getElementById("c");
  var rect = c.getBoundingClientRect();
  c.width = rect.width;
  c.height = rect.height;
  redrawCanvas(c);
}
</script>
<canvas id="c" onfullscreenchange="resizeCanvas()"></canvas>
<button onclick="document.getElementById('c').requestFullScreen()">
  Go Fullscreen!
</button>

3. Hide advertisements while the window is fullscreen.

@media all and (full-screen:on) {
  .advertisement { display:none; }
}

Issues

naming one word or two

fullscreen vs full screen

• fullscreen
  • text of this page repeatedly uses "fullscreen"
  • Wikipedia prefers "fullscreen" and redirects "full screen" to that page.

• full screen
  • title of this page implies "full screen" from the camelcase: (FullScreenAPI)
  • the Firefox 4 "View" menu item "Full Screen" (shift-command-F)

Whichever we pick, we should be consistent, e.g., EITHER:

1. one word

• fullscreen
  • :fullscreen
  • media query selector feature: fullscreen
  • cancelFullscreen()
  • requestFullscreen()
  • requestFullscreenWithKeys()

OR

2. two words

• full screen
  • :full-screen
  • media query selector feature: full-screen
  • cancelFullScreen()
  • requestFullScreen()
  • requestFullScreenWithKeys()

OR

3. come up with a good case (e.g. CSS vs DOM) to split them consistently:

• full screen
  • :fullscreen
  • media query selector feature: fullscreen
  • cancelFullScreen()
  • requestFullScreen()
  • requestFullScreenWithKeys()

media type vs media query selector

@media full-screen vs. @media all and (full-screen: on)

Originally spec'd:

New CSS media type:

• full-screen

While a Document is in the fullscreen state, the full-screen media type is active for the document.

Per discussion among User:Fantasai, User:Roc, User:Tantek a media query selector for the fullscreen state (on or off) may be better, e.g. it can be combined with all media types:

@media all and (full-screen: on)

or can be special cased for specific media types:

@media handheld and (full-screen: on)

@media screen and (full-screen: on)

@media tv and (full-screen: on)

If we resolve the naming issue based on one word rather than two, then we'll rename this CSS feature accordingly ( :fullscreen , media query selector "fullscreen" )