MozillaWiki

Gecko:FullScreenAPI: Difference between revisions

Gecko Discussion

Gecko:FullScreenAPI (view source)

Revision as of 18:23, 21 December 2013

5,429 bytes added ,  21 December 2013
remove spam Undo revision 809159 by Seotoolinfo (talk)
(Implementations)
(remove spam Undo revision 809159 by Seotoolinfo (talk))
 
(31 intermediate revisions by 5 users not shown)
Line 18: Line 18:
* Content in IFRAMEs should be able go full-screen
* Content in IFRAMEs should be able go full-screen
** To enable "widgets" such as embedded videos to offer full-screen UI
** To enable "widgets" such as embedded videos to offer full-screen UI
''cpearce: Scripts should be able to determine whether full-screen requests are likely to be granted from the current frame (so that video players in an embedded iframe know whether they should show a full-screen button in their UI).''


== Proposed Specification ==
== Proposed Specification ==
Line 33: Line 35:
* DOM_VK_SEMICOLON to DOM_VK_EQUALS, inclusive
* DOM_VK_SEMICOLON to DOM_VK_EQUALS, inclusive
* DOM_VK_MULTIPLY to DOM_VK_META, 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 full-screen mode.
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 full-screen mode (disputed, may be better to stay in full-screen mode and instead put up the in-fullscreen warning, "press esc to exit" etc.).
 
Keypress whitelist:
* tab, space, arrow keys, page-up, page-down, home, end
* shift, ctrl, alt/option, command
** and combinations thereof, with the previous set of keys (except command/ctrl-tab)


Each document has an optional "current full-screen element".
Each document has an optional "current full-screen element".


=== Document additions ===
==== cancelFullScreen method ====
New method of Document:
New method of Document:


Line 45: Line 54:
The current full-screen element for the document is cleared.
The current full-screen element for the document is cleared.


==== fullScreen attribute ====
New DOM attribute of Document:
* readonly attribute boolean fullScreen
Returns true while the document is in the full-screen state.
==== fullScreenKeyboardInputAllowed attribute ====
New DOM attribute of Document:
* readonly attribute boolean fullScreenKeyboardInputAllowed
Returns true while the window's toplevel browsing context is full-screen and not in a "keys disabled" state.
==== fullScreenEnabled attribute ====
New DOM attribute of Document:
* readonly attribute boolean fullScreenEnabled
Returns true if requests for full-screen in the current document are likely to not be denied because of security or UA constraints. Typically this means all containing frames have the allowfullscreen attribute present.
=== Element additions ===
New methods of Element:
New methods of Element:


==== requestFullScreenWithKeys method ====
* void requestFullScreenWithKeys()
* void requestFullScreenWithKeys()


Line 53: Line 85:
Typically the user agent would react by transitioning the Document to the full-screen state, or by presenting asynchronous confirmation UI and transitioning to the full-screen 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).
Typically the user agent would react by transitioning the Document to the full-screen state, or by presenting asynchronous confirmation UI and transitioning to the full-screen 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).


==== requestFullScreen method ====
* void requestFullScreen()
* void requestFullScreen()


As requestFullScreenWithKeys, but hints to the UA that while in full-screen 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 full-screen state with keys disabled.
As requestFullScreenWithKeys, but hints to the UA that while in full-screen 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 full-screen state with keys disabled.


New DOM attribute of Document:
''cpearce: We are planning on dispatching a "fullscreendenied" event when requests for full-screen are denied. We changed to an "ask forgiveness" model, rather than an "ask permission" model, so requests can be approved/denied immediately in requestFullScreen(). UAs which choose to implement requestFullScreen with an "ask permission" model may never end up sending a "fullscreendenied" event however.''


* readonly attribute boolean fullScreen
==== fullscreenchange event ====
New events:


Returns true while the document is in the full-screen state.
* fullscreenchange


* readonly attribute boolean fullScreenKeyboardInputAllowed
When a Document enters or leaves the full-screen state, the user agent must queue a task to dispatch this event. When the event is dispatched, if the document's current full-screen 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.


Returns true while the window's toplevel browsing context is full-screen and not in a "keys disabled" state.
==== onfullscreenchange attribute ====
The 'onfullscreenchange' event handling attribute is supported on HTML elements.


==== iframe allowfullscreen attribute ====
New content attribute of the <iframe> element:
New content attribute of the <iframe> element:


Line 73: Line 109:
This is a boolean attribute. When this attribute is not set, UAs must ignore full-screen requests in the iframe or its descendant frames.
This is a boolean attribute. When this attribute is not set, UAs must ignore full-screen requests in the iframe or its descendant frames.


New events:
=== CSS additions ===
 
==== full-screen pseudo-class ====
* fullscreenchange
New CSS pseudo-class:
 
When a Document enters or leaves the full-screen state, the user agent must queue a task to dispatch this event. When the event is dispatched, if the document's current full-screen 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
* :full-screen
Line 87: Line 117:
While a Document is in the full-screen state, and the document's current full-screen 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 full-screen state has the 'full-screen' pseudoclass applied.
While a Document is in the full-screen state, and the document's current full-screen 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 full-screen state has the 'full-screen' pseudoclass applied.


New CSS media query selector:
==== full-screen-ancestor pseudo-class ====
New CSS pseudo-class:
* :full-screen-ancestor


* <code>full-screen</code>
While a Document is in the full-screen state, and the document's current full-screen element is an element in the document, the 'full-screen-ancestor' pseudoclass applies to ancestors of the full-screen element.


that accepts two states:
==== view-mode ====


* <code>on</code>
http://www.w3.org/TR/view-mode/ introduces a "view-mode" media feature with possible value "fullscreen". That should be implemented alongside the rest of this specification.
* <code>off</code>


Note from fantasai: http://www.w3.org/TR/view-mode/ covers this already
==== UA stylesheet rules ====
 
While a Document is in the full-screen state, the full-screen media type is active for the document.


Suggested UA stylesheet rules:
Suggested UA stylesheet rules:
Line 112: Line 141:
   z-index:2147483647;
   z-index:2147483647;
   background:black;
   background:black;
  /* override mapped width and height attributes */
  width:100% !important;
  height:100% !important;
  }
  }
  /* In full-screen mode, if the root element itself is not full-screen then
  /* If there is a full-screen element that is not the root then
     we should hide the viewport scrollbar. */
     we should hide the viewport scrollbar. */
  @media all and (full-screen:on) {
  :root:full-screen-ancestor {
   :root:not(:full-screen) {
  overflow:hidden;
    overflow:hidden;
}
   }
:full-screen-ancestor {
  /* Ancestors of a full-screen element should not induce stacking contexts
      that would prevent the full-screen element from being on top. */
   z-index:auto;
  /* Ancestors of a full-screen element should not be partially transparent,
      since that would apply to the full-screen element and make the page visible
      behind it. It would also create a pseudo-stacking-context that would let content
      draw on top of the full-screen element. */
  opacity:1;
  /* Ancestors of a full-screen element should not apply SVG masking, clipping, or
      filtering, since that would affect the full-screen element and create a pseudo-
      stacking context. */
  mask:none;
  clip:auto;
   filter:none;
  }
  }


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'.
For these to be effective, we really want their to be higher precedence than non-important author rules. So we need to add a new precedence level for UA style rules that's between "author" and "author important". Gecko already supports this via "override styles sheets" (nsIPresShell::AddOverrideStyleSheet), already used by the editor.
 
==== Webkit additions ====
New CSS pseudo-classes:
* :full-screen-document - While a Document is in the fullscreen state, the 'full-screen-document' pseudo-class applies to the root element of that Document.
** note: webkit has implemented previous name for this :full-screen-doc
* :full-screen-root-with-target - While a Document is in the fullscreen state and the document's current fullscreen element is an element in the document, the 'full-screen-root-with-target' pseudoclass applies to the root element of that Document.
 
These are unnecessary given the above features. ":full-screen-document { ... }" can be written "@media all and (view-mode: fullscreen) { :root { ... } }". ":full-screen-root-with-target { ... }" can be written ":root:full-screen-ancestor, :root:full-screen { ... }".
 
See [http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2010-August/027670.html feedback on new pseudo-classes] and [http://lists.whatwg.org/pipermail/whatwg-whatwg.org/2010-August/027672.html follow-up from RoC] (and subsequent thread)


== Suggested UA Policy ==
== Suggested UA Policy ==
Line 174: Line 230:
  }
  }
== Security ==
== Security ==
Date of discussion: 2011.04.11
Discussions documented newest first.


Security Concerns:
=== Discussion 2011-10-03 ===
* Ability of website to enter fullscreen and pre-empt keyboard focus
* [[Security/Reviews/Firefox10/CodeEditor/FullScreenAPI]]
* User interaction currently not required for entering full screen mode
* comparisons made to Flash's restrictions, e.g. as documented in [http://www.adobe.com/devnet/flashplayer/articles/full_screen_mode.html Exploring full-screen mode in Flash Player] and [http://kb2.adobe.com/cps/405/kb405548.html Limited full-screen keyboard input (Flash Player 10)].
* Fullscreen could be used as an attack vector
Responses:
* There is a mode called without keys that does not take keyboard input
* Focus is released on tab change or window change
Possible Remediations:
* ESC key should be used to exit, similar to other well known apps users are familiar with
* A user preference should be available for users to say allow full-screen or dis-allow full screen for a given URL domain (Ie. Popup or geolocation preferences)
* Possible use of some indicator to show a user they are in full-screen mode
* Possible use of permission manager
* Plug-ins should be disabled when in full-screen mode
To-Do
* Re-review as spec firms up and code begins to land


=== Jesse's concerns ===
=== Discussion 2011-04-21 ===
Added 2011-04-21
Jesse's concerns, added 2011-04-21.


I'm worried about having a full screen mode that does not require user permission. In particular, I have three concerns:
I'm worried about having a full screen mode that does not require user permission. In particular, I have three concerns:
Line 230: Line 274:


''Jesse 2011-08-18'': Interesting to note that IE previously had fullscreen=yes but [https://developer.mozilla.org/en/Window.open#Note_on_fullscreen removed it in WinXP SP2].
''Jesse 2011-08-18'': Interesting to note that IE previously had fullscreen=yes but [https://developer.mozilla.org/en/Window.open#Note_on_fullscreen removed it in WinXP SP2].
=== Discussion 2011-04-11 ===
Date of discussion: 2011.04.11
Security Concerns:
* Ability of website to enter fullscreen and pre-empt keyboard focus
* User interaction currently not required for entering full screen mode
* Fullscreen could be used as an attack vector
Responses:
* There is a mode called without keys that does not take keyboard input
* Focus is released on tab change or window change
Possible Remediations:
* ESC key should be used to exit, similar to other well known apps users are familiar with
* A user preference should be available for users to say allow full-screen or dis-allow full screen for a given URL domain (Ie. Popup or geolocation preferences)
* Possible use of some indicator to show a user they are in full-screen mode
* Possible use of permission manager
* Plug-ins should be disabled when in full-screen mode
To-Do
* Re-review as spec firms up and code begins to land


== Issues ==
== Issues ==
Line 239: Line 302:
** text of this page repeatedly uses "fullscreen"
** text of this page repeatedly uses "fullscreen"
** Wikipedia prefers "[https://secure.wikimedia.org/wikipedia/en/wiki/Fullscreen fullscreen]" and redirects "[https://secure.wikimedia.org/wikipedia/en/wiki/Full_screen full screen]" to that page.
** Wikipedia prefers "[https://secure.wikimedia.org/wikipedia/en/wiki/Fullscreen fullscreen]" and redirects "[https://secure.wikimedia.org/wikipedia/en/wiki/Full_screen full screen]" to that page.
** the combined term "fullscreen" is more easily uniquely searchable than separate terms


* '''full screen'''
* '''full screen'''
** title of this page implies "full screen" from the camelcase: ([[Gecko:FullScreenAPI|FullScreenAPI]])
** title of this page implies "full screen" from the camelcase: ([[Gecko:FullScreenAPI|FullScreenAPI]]) - but that's just legacy.
** the Firefox 4 "View" menu item "Full Screen" (shift-command-F)
** the Firefox 4 "View" menu item "Full Screen" (shift-command-F)


''roc: Elika and I resolved to use 'full-screen' everywhere.''
<div class=discussion>
* ''roc: Elika and I resolved to use 'full-screen' everywhere.''
** Why? It would be useful to have reasoning documented for this conclusion so we can avoid re-exploring it. [[User:Tantek|Tantek]]
</div>


=== avoiding ancestor reflow ===
=== avoiding ancestor reflow ===
Line 269: Line 336:
In progress:
In progress:
* [[Platform/Features/Full_Screen_APIs|Firefox Platform/Features/Full_Screen_APIs]]
* [[Platform/Features/Full_Screen_APIs|Firefox Platform/Features/Full_Screen_APIs]]
* Webkit
** [http://blog.pearce.org.nz/2011/09/mozilla-full-screen-api-progress-update.html 2011-09-22 Mozilla full-screen API progress update]
* [http://trac.webkit.org/changeset/92576 WebKit Checkin]
** [http://codereview.chromium.org/7461059/ Chrome review]
** [http://peter.sh/2011/01/javascript-full-screen-api-navigation-timing-and-repeating-css-gradients/ Safari Webkit nightlies have support]
 
[[Category:Web APIs]]
 
== Articles ==
* 2011-10-26 [http://updates.html5rocks.com/2011/10/Let-Your-Content-Do-the-Talking-Fullscreen-API Let Your Content Do the Talking: Fullscreen API]
* 2012-06-06 [http://sorcery.smugmug.com/2012/06/06/using-html5s-fullscreen-api-for-fun-and-profit/ Using HTML5′s Fullscreen API for Fun and Profit]
Tantek
canmove, Confirmed users
2,887

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/342020...814673"