2 | Group: WHATWG 3 | H1: Fullscreen API 4 | Shortname: fullscreen 5 | Text Macro: TWITTER fullscreenapi 6 | Text Macro: LATESTRD 2024-07 7 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 8 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 9 | Translation: zh-Hans https://htmlspecs.com/fullscreen/ 10 | Markup Shorthands: css no 11 |12 | 13 |
14 | spec:dom 15 | type:dfn; for:/; text:document 16 | type:dfn; for:/; text:element 17 | type:interface; text:Document 18 | spec:infra 19 | type:dfn; for:set; text:for each 20 | type:dfn; text:string 21 | spec:css-position-4 22 | type:selector; text: ::backdrop 23 | type:dfn; text:top layer 24 |25 | 26 |
27 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 28 | type: dfn 29 | text: triggered by a user generated orientation change 30 |31 | 32 |
33 | {
34 | "CSS": {
35 | "aliasOf": "CSS2"
36 | },
37 | "SVG": {
38 | "aliasOf": "SVG11"
39 | }
40 | }
41 |
42 |
43 |
44 |
45 | This specification depends on the Infra Standard. [[!INFRA]] 48 | 49 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 50 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 51 | 52 | 53 | 54 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 57 | unset. 58 | 59 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 60 | stated otherwise it is unset. 61 | 62 |
All documents have an associated fullscreen element. The 63 | fullscreen element is the topmost element in the document's 64 | top layer whose fullscreen flag is set, if any, and null otherwise. 65 | 66 |
All documents have an associated list of pending fullscreen events, which 67 | is an ordered set of (string, element) tuples. It is initially empty. 68 | 69 |
To fullscreen an element: 70 | 71 |
Let hideUntil be the result of running topmost popover ancestor given 73 | element, null, and false. 74 | 75 |
If hideUntil is null, then set hideUntil to element's 76 | node document. 77 | 78 |
Run hide all popovers until given hideUntil, false, and true. 79 | 80 |
Set element's fullscreen flag. 81 | 82 |
Remove from the top layer immediately given element. 83 | 84 |
To unfullscreen an element, unset element's 88 | fullscreen flag and iframe fullscreen flag (if any), and 89 | remove from the top layer immediately given element. 90 | 91 |
To unfullscreen a document, 92 | unfullscreen all elements, within document's 93 | top layer, whose fullscreen flag is set. 94 | 95 |
To fully exit fullscreen a document document, run these steps: 99 | 100 |
If document's fullscreen element is null, terminate these steps. 102 | 103 |
Unfullscreen elements whose fullscreen flag is 104 | set, within document's top layer, except for document's 105 | fullscreen element. 106 | 107 |
Exit fullscreen document. 108 |
Whenever the removing steps run with a removedNode, run 113 | these steps: 114 | 115 |
Let document be removedNode's node document. 117 | 118 |
Let nodes be removedNode's 119 | shadow-including inclusive descendants that have their fullscreen flag set, in 120 | shadow-including tree order. 121 | 122 |
For each node in nodes: 124 | 125 |
If node is document's fullscreen element, 127 | exit fullscreen document. 128 | 129 |
Otherwise, unfullscreen node. 130 | 131 |
If document's top layer contains node, 133 | remove from the top layer immediately given node. 134 | 135 |
Other specifications can add and remove elements from top layer, so 136 | node might not be document's fullscreen element. For example, 137 | node could be an open <{dialog}> element. 138 |
Whenever the unloading document cleanup steps run with a document, 143 | fully exit fullscreen document. 144 | 145 |
Fullscreen is supported if there is no previously-established user preference, 148 | security risk, or platform limitation. 149 | 150 |
To run the fullscreen steps for a document document, run these 154 | steps: 155 | 156 |
Let pendingEvents be document's 158 | list of pending fullscreen events. 159 | 160 |
Empty document's list of pending fullscreen events. 161 | 162 |
For each (type, element) in pendingEvents: 164 | 165 |
Let target be element if element is connected 167 | and its node document is document, and otherwise let target be 168 | document. 169 | 170 |
Fire an event named type, with its {{Event/bubbles}} and 171 | {{Event/composed}} attributes set to true, at target. 172 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 176 |
183 | enum FullscreenNavigationUI {
184 | "auto",
185 | "show",
186 | "hide"
187 | };
188 |
189 | dictionary FullscreenOptions {
190 | FullscreenNavigationUI navigationUI = "auto";
191 | };
192 |
193 | partial interface Element {
194 | Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});
195 |
196 | attribute EventHandler onfullscreenchange;
197 | attribute EventHandler onfullscreenerror;
198 | };
199 |
200 | partial interface Document {
201 | [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
202 | [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
203 |
204 | Promise<undefined> exitFullscreen();
205 |
206 | attribute EventHandler onfullscreenchange;
207 | attribute EventHandler onfullscreenerror;
208 | };
209 |
210 | partial interface mixin DocumentOrShadowRoot {
211 | [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
212 | };
213 |
214 |
216 |
217 | promise = element . requestFullscreen([options])
219 | document . {{Document/fullscreenEnabled}}
230 | Returns true if document has the ability to display elements fullscreen 231 | and fullscreen is supported, or false otherwise. 232 | 233 |
promise = document . {{Document/exitFullscreen()}}
234 | Stops document's fullscreen element from being displayed fullscreen and 235 | resolves promise when done. 236 | 237 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
238 | Returns document's fullscreen element. 239 | 240 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
241 | Returns shadowroot's fullscreen element. 242 |
A fullscreen element ready check for an element element returns true 245 | if all of the following are true, and false otherwise: 246 | 247 |
element is connected. 249 | 250 |
element's node document is allowed to use the "fullscreen" feature.
252 |
253 |
254 |
element namespace is not the HTML namespace or 255 | element's popover visibility state is hidden. 257 |
The requestFullscreen(options) method steps
261 | are:
262 |
263 |
Let pendingDoc be this's node document. 265 | 266 |
Let promise be a new promise. 267 | 268 |
If pendingDoc is not fully active, then reject promise with a 269 | {{TypeError}} exception and return promise. 270 | 271 |
Let error be false. 272 | 273 |
If any of the following conditions are false, then set error to true: 275 | 276 |
This's namespace is the HTML namespace or
278 | this is an
279 | SVG svg or
280 | MathML math
281 | element. [[!SVG]] [[!MATHML]]
282 |
283 |
This is not a <{dialog}> element. 284 | 285 |
The fullscreen element ready check for this returns true. 286 | 287 |
Fullscreen is supported. 288 | 289 |
This's relevant global object has transient activation or the 290 | algorithm is triggered by a user generated orientation change. 291 |
If error is false, then consume user activation given 294 | pendingDoc's relevant global object. 295 | 296 |
Return promise, and run the remaining steps in parallel. 297 | 298 |
If error is false, then resize pendingDoc's node navigable's 300 | top-level traversable's active document's viewport's 301 | dimensions, optionally taking into account 302 | options["{{FullscreenOptions/navigationUI}}"]: 303 | 304 | 305 |
| value | 309 |viewport dimensions | 310 |
|---|---|
"hide" |
315 | full dimensions of the screen of the output device | 316 |
"show" |
319 | dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | 320 |
"auto" |
323 | user-agent defined, but matching one of the above | 324 |
Optionally display a message how the end user can revert this. 329 | 330 |
If any of the following conditions are false, then set error to true: 332 | 333 |
This's node document is pendingDoc. 335 | 336 |
The fullscreen element ready check for this returns true. 337 | 338 |
If error is true: 342 | 343 |
Append ({{fullscreenerror}}, this) to 345 | pendingDoc's list of pending fullscreen events. 346 | 347 |
Reject promise with a {{TypeError}} exception and terminate these 348 | steps. 349 |
Let fullscreenElements be an ordered set initially consisting of 352 | this. 353 | 354 |
While true: 356 | 357 |
Let last be the last item of fullscreenElements. 359 | 360 |
Let container be last's node navigable's 361 | container. 362 | 363 |
If container is null, then break. 364 | 365 |
Append container to fullscreenElements. 366 |
For each element in fullscreenElements: 372 | 373 |
Let doc be element's node document. 375 | 376 |
If element is doc's fullscreen element, continue. 378 | 379 |
No need to notify observers when nothing has changed. 380 | 381 |
If element is this and this is an <{iframe}> 382 | element, then set element's iframe fullscreen flag. 383 | 384 |
Fullscreen element within doc. 385 | 386 |
Append ({{fullscreenchange}}, element) to 387 | doc's list of pending fullscreen events. 388 |
The order in which elements are fullscreened 391 | is not observable, because run the fullscreen steps is invoked in tree order. 392 | 393 |
Resolve promise with undefined. 394 |
Implementations with out-of-process navigables are left as an exercise 397 | to the reader. Input welcome on potential improvements. 398 |
The fullscreenEnabled getter steps are to return
401 | true if this is allowed to use the "fullscreen" feature and fullscreen is supported, and
403 | false otherwise.
404 |
405 |
The fullscreen getter steps are to return false if
406 | this's fullscreen element is null, and true otherwise.
407 |
408 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 409 | 410 |
The
412 | fullscreenElement
413 | getter steps are:
414 |
415 |
If this is a shadow root and its host is not 417 | connected, then return null. 418 | 419 |
Let candidate be the result of retargeting fullscreen element 420 | against this. 421 | 422 |
If candidate and this are in the same tree, then return 423 | candidate. 424 | 425 |
Return null. 426 |
A document is said to be a simple fullscreen document if there is exactly one 430 | element in its top layer that has its fullscreen flag set. 431 | 432 |
A document with two elements in its top layer can be a 433 | simple fullscreen document. For example, in addition to the fullscreen element there 434 | could be an open <{dialog}> element. 435 | 436 |
To collect documents to unfullscreen given doc, run these steps: 438 | 439 |
Let docs be an ordered set consisting of doc. 441 | 442 |
While true: 444 | 445 |
Let lastDoc be docs's last document. 447 | 448 |
Assert: lastDoc's fullscreen element is not null. 449 | 450 |
If lastDoc is not a simple fullscreen document, break. 451 | 452 |
Let container be lastDoc's node navigable's 453 | container. 454 | 455 |
If container is null, then break. 456 | 457 |
If container's iframe fullscreen flag is set, break. 458 | 459 |
Append container's node document to docs. 460 |
Return docs. 463 | 464 |
This is the set of documents for which the fullscreen element will be 465 | unfullscreened, but the last document in docs might 466 | have more than one element in its top layer with the fullscreen flag set, 467 | in which case that document will still remain in fullscreen. 468 |
To exit fullscreen a document doc, run these steps: 473 | 474 |
Let promise be a new promise. 476 | 477 |
If doc is not fully active or doc's fullscreen element 478 | is null, then reject promise with a {{TypeError}} exception and return 479 | promise. 480 | 481 |
Let resize be false. 482 | 483 |
Let docs be the result of 484 | collecting documents to unfullscreen given 485 | doc. 486 | 487 | 488 |
Let topLevelDoc be doc's node navigable's 489 | top-level traversable's active document. 490 | 491 | 492 |
If topLevelDoc is in docs, and it is a 493 | simple fullscreen document, then set doc to topLevelDoc and 494 | resize to true. 495 | 496 |
If doc's fullscreen element is not connected: 497 |
Append ({{fullscreenchange}}, doc's fullscreen element) 499 | to doc's list of pending fullscreen events. 500 | 501 |
Unfullscreen doc's fullscreen 502 | element. 503 |
Return promise, and run the remaining steps in parallel. 506 | 507 |
Run the [=fully unlock the screen orientation steps=] with doc. 508 | 509 |
If resize is true, resize doc's viewport to its "normal" dimensions. 510 | 511 |
If doc's fullscreen element is null, then resolve promise with 512 | undefined and terminate these steps. 513 | 514 |
Let exitDocs be the result of 515 | collecting documents to unfullscreen given 516 | doc. 517 | 518 | 519 |
Let descendantDocs be an ordered set consisting of doc's 520 | descendant navigables' active documents whose 521 | fullscreen element is non-null, if any, in tree order. 522 | 523 | 524 |
For each exitDoc in exitDocs: 526 | 527 |
Append ({{fullscreenchange}}, exitDoc's 529 | fullscreen element) to exitDoc's list of pending fullscreen events. 530 | 531 |
If resize is true, unfullscreen 532 | exitDoc. 533 | 534 |
Otherwise, unfullscreen exitDoc's 535 | fullscreen element. 536 |
For each descendantDoc in descendantDocs: 540 | 541 |
Append ({{fullscreenchange}}, descendantDoc's 543 | fullscreen element) to descendantDoc's 544 | list of pending fullscreen events. 545 | 546 |
Unfullscreen descendantDoc. 547 |
The order in which documents are unfullscreened 550 | is not observable, because run the fullscreen steps is invoked in tree order. 551 | 552 |
Resolve promise with undefined. 553 |
The exitFullscreen() method steps are to return the
557 | result of running exit fullscreen on this.
558 |
559 |
The following are the event handlers (and their corresponding 562 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 563 | event handler IDL attributes: 564 | 565 |
| event handler 569 | | event handler event type 570 | |
|---|---|
onfullscreenchange
573 | | fullscreenchange
574 | |
onfullscreenerror
576 | | fullscreenerror
577 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 580 | corresponding event handler content attributes for {{Element}} objects in any namespace. 581 | 582 | 583 | 584 |
User agents are encouraged to implement native media fullscreen controls in terms of 587 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 588 | 589 |
If the end user instructs the user agent to end a fullscreen session initiated via 590 | {{Element/requestFullscreen()}}, fully exit fullscreen given the 591 | top-level traversable's active document. 592 | 593 |
The user agent may end any fullscreen session without instruction from the end user 594 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 595 | 596 | 597 | 598 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 601 | 602 | 603 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
606 | element element for which one of the following conditions is true:
607 |
608 |
element's fullscreen flag is set. 610 | 611 |
element is a shadow host and the result of retargeting its 612 | node document's fullscreen element against element is element. 613 |
This makes it different from the 616 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 617 | 618 |
622 | @namespace "http://www.w3.org/1999/xhtml";
623 |
624 | *|*:not(:root):fullscreen {
625 | position:fixed !important;
626 | inset:0 !important;
627 | margin:0 !important;
628 | box-sizing:border-box !important;
629 | min-width:0 !important;
630 | max-width:none !important;
631 | min-height:0 !important;
632 | max-height:none !important;
633 | width:100% !important;
634 | height:100% !important;
635 | transform:none !important;
636 |
637 | /* intentionally not !important */
638 | object-fit:contain;
639 | }
640 |
641 | iframe:fullscreen {
642 | border:none !important;
643 | padding:0 !important;
644 | }
645 |
646 | *|*:not(:root):fullscreen::backdrop {
647 | background:black;
648 | }
649 |
650 |
651 |
652 |
653 | This specification defines a policy-controlled feature identified by the string
657 | "fullscreen". Its default allowlist is
658 | 'self'.
659 |
660 |
A document's permissions policy determines whether any content in that 662 | document is allowed to go fullscreen. If disabled in any document, no content in the document will 663 | be allowed to use fullscreen. 664 | 665 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
666 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
667 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
668 | allow="fullscreen *">, as described in
669 | [[permissions-policy#iframe-allowfullscreen-attribute]].
670 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 677 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 678 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 679 | user agent or even operating system environment when fullscreen. See also the definition of 680 | {{Element/requestFullscreen()}}. 681 | 682 |
To enable content in a child navigable to go fullscreen, it needs to be specifically
683 | allowed via permissions policy, either through the <{iframe/allowfullscreen}> attribute of the HTML
684 | <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the HTML
685 | <{iframe}> element, or through a `Permissions-Policy` HTTP header
686 | delivered with the document through which it is nested.
687 |
688 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 689 | 690 | 691 | 692 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 702 | 703 | 704 |
Thanks to 705 | Andy Earnshaw, 706 | Changwan Hong, 707 | Chris Pearce, 708 | Darin Fisher, 709 | Dave Tapuska, 710 | fantasai, 711 | Giuseppe Pascale, 712 | Glenn Maynard, 713 | Ian Clelland, 714 | Ian Hickson, 715 | Ignacio Solla, 716 | João Eiras, 717 | Josh Soref, 718 | Kagami Sascha Rosylight, 719 | Matt Falkenhagen, 720 | Mihai Balan, 721 | Mounir Lamouri, 722 | Øyvind Stenhaug, 723 | Pat Ladd, 724 | Rafał Chłodnicki, 725 | Riff Jiang, 726 | Rune Lillesveen, 727 | Sigbjørn Vik, 728 | Simon Pieters, 729 | Tab Atkins-Bittner, 730 | Takayoshi Kochi, 731 | Theresa O'Connor, 732 | triple-underscore, 733 | Vincent Scheib, and 734 | Xidorn Quan 735 | for also being awesome. 736 | 737 |
This standard is edited by Philip Jägenstedt 738 | (Google, 739 | philip@foolip.org). It was originally written by 740 | Anne van Kesteren 741 | (Apple, annevk@annevk.nl). 742 | Tantek Çelik 743 | (Mozilla, 744 | tantek@cs.stanford.edu) sorted out legal hassles. 745 | -------------------------------------------------------------------------------- /review-drafts/2018-07.bs: -------------------------------------------------------------------------------- 1 |
2 | Group: WHATWG 3 | Date: 2018-07-23 4 | H1: Fullscreen API 5 | Shortname: fullscreen 6 | Text Macro: TWITTER fullscreenapi 7 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 8 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 9 |10 | 11 |
12 | spec:dom 13 | type:dfn; for:/; text:element 14 | type:interface; text:Document 15 | spec:infra 16 | type:dfn; for:set; text:for each 17 | type:dfn; text:string 18 |19 | 20 |
21 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 22 | type: dfn 23 | text: triggered by a user generated orientation change 24 |25 | 26 |
27 | {
28 | "CSS": {
29 | "aliasOf": "CSS2"
30 | },
31 | "SVG": {
32 | "aliasOf": "SVG11"
33 | }
34 | }
35 |
36 |
37 |
38 |
39 | This specification depends on the Infra Standard. [[!INFRA]] 42 | 43 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 44 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 45 | 46 |
A browsing context A is called a descendant browsing context 47 | of a browsing context B if and only if B is an 48 | ancestor browsing context of A. 49 | 50 | 51 | 52 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 55 | unset. 56 | 57 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 58 | stated otherwise it is unset. 59 | 60 |
All documents have an associated fullscreen element. The 61 | fullscreen element is the topmost element in the document's 62 | top layer whose fullscreen flag is set, if any, and null otherwise. 63 | 64 |
All documents have an associated list of pending fullscreen events, which 65 | is an ordered set of (string, element) pairs. It is initially empty. 66 | 67 |
To fullscreen an element, set element's fullscreen flag 68 | and add it to its node document's top layer. 69 | 70 |
To unfullscreen an element, unset element's 71 | fullscreen flag and iframe fullscreen flag (if any), and remove it from 72 | its node document's top layer. 73 | 74 |
To unfullscreen a document, 75 | unfullscreen all elements, within document's 76 | top layer, whose fullscreen flag is set. 77 | 78 |
To fully exit fullscreen a document document, run these steps: 81 | 82 |
If document's fullscreen element is null, terminate these steps. 84 | 85 |
Unfullscreen elements whose fullscreen flag is 86 | set, within document's top layer, except for document's 87 | fullscreen element. 88 | 89 |
Exit fullscreen document. 90 |
Whenever the removing steps run with a removedNode, run 93 | these steps: 94 | 95 |
Let nodes be removedNode's 97 | shadow-including inclusive descendants that have their fullscreen flag set, in 98 | shadow-including tree order. 99 | 100 |
For each node in nodes: 102 | 103 |
If node is its node document's fullscreen element, 105 | exit fullscreen that document. 106 | 107 |
Otherwise, unfullscreen node within its 108 | node document. 109 |
Whenever the unloading document cleanup steps run with a document, 113 | fully exit fullscreen document. 114 | 115 |
Fullscreen is supported if there is no previously-established user preference, 118 | security risk, or platform limitation. 119 | 120 |
An algorithm is allowed to request fullscreen if one of the following is true: 121 | 122 |
The algorithm is triggered by user activation. 124 | 125 |
The algorithm is triggered by a user generated orientation change. 126 |
To run the fullscreen steps for a document document, run these 132 | steps: 133 | 134 |
Let pairs be document's list of pending fullscreen events. 136 | 137 |
Empty document's list of pending fullscreen events. 138 | 139 |
For each (type, element) in pairs: 141 | 142 |
Let target be element if element is connected 144 | and its node document is document, and otherwise let target be 145 | document. 146 | 147 |
Fire an event named type, with its {{Event/bubbles}} and 148 | {{Event/composed}} attributes set to true, at target. 149 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 153 | 154 | 155 | 156 |
159 | partial interface Element {
160 | Promise<void> requestFullscreen();
161 |
162 | attribute EventHandler onfullscreenchange;
163 | attribute EventHandler onfullscreenerror;
164 | };
165 |
166 | partial interface Document {
167 | [LenientSetter] readonly attribute boolean fullscreenEnabled;
168 | [LenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
169 |
170 | Promise<void> exitFullscreen();
171 |
172 | attribute EventHandler onfullscreenchange;
173 | attribute EventHandler onfullscreenerror;
174 | };
175 |
176 | partial interface DocumentOrShadowRoot {
177 | [LenientSetter] readonly attribute Element? fullscreenElement;
178 | };
179 |
180 |
182 |
183 | promise = element . {{Element/requestFullscreen()}}
185 | Displays element fullscreen and resolves promise when done. 186 | 187 |
document . {{Document/fullscreenEnabled}}
188 | Returns true if document has the ability to display elements fullscreen 189 | and fullscreen is supported, or false otherwise. 190 | 191 |
promise = document . {{Document/exitFullscreen()}}
192 | Stops document's fullscreen element from being displayed fullscreen and 193 | resolves promise when done. 194 | 195 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
196 | Returns document's fullscreen element. 197 | 198 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
199 | Returns shadowroot's fullscreen element. 200 |
A fullscreen element ready check for an element element returns true 203 | if all of the following are true, and false otherwise: 204 | 205 |
element is connected. 207 | 208 |
element's node document is allowed to use the "fullscreen" feature.
210 |
211 |
The requestFullscreen() method, when invoked, must run
214 | these steps:
215 |
216 |
Let pending be the context object. 218 | 219 |
Let pendingDoc be pending's node document. 220 | 221 |
Let promise be a new promise. 222 | 223 |
If pendingDoc is not fully active, then reject promise with a
224 | TypeError exception and return promise.
225 |
226 |
Let error be false. 227 | 228 |
If any of the following conditions are false, then set error to true: 230 | 231 |
pending's namespace is the HTML namespace or
233 | pending is an
234 | SVG svg or
235 | MathML math
236 | element. [[!SVG]] [[!MATHML]]
237 |
238 |
pending is not a <{dialog}> element. 239 | 240 |
The fullscreen element ready check for pending returns true. 241 | 242 |
Fullscreen is supported. 243 | 244 |
This algorithm is allowed to request fullscreen. 245 |
Return promise, and run the remaining steps in parallel. 248 | 249 |
If error is false: Resize pendingDoc's 250 | top-level browsing context's active document's viewport's dimensions to match the 251 | dimensions of the screen of the output device. Optionally display a message how the end user can 252 | revert this. 253 | 254 | 255 |
If any of the following conditions are false, then set error to true: 257 | 258 |
pending's node document is pendingDoc. 260 | 261 |
The fullscreen element ready check for pending returns true. 262 | 263 |
If error is true: 267 | 268 |
Append (fullscreenerror, pending) to
270 | pendingDoc's list of pending fullscreen events.
271 |
272 |
Reject promise with a TypeError exception and terminate these
273 | steps.
274 |
Let fullscreenElements be an ordered set initially consisting of 277 | pending. 278 | 279 |
While the first element in fullscreenElements is in a 280 | nested browsing context: append its browsing context container to 281 | fullscreenElements. 282 | 283 | 284 |
For each element in fullscreenElements: 286 | 287 |
Let doc be element's node document. 289 | 290 |
If element is doc's fullscreen element, continue. 292 | 293 |
No need to notify observers when nothing has changed. 294 | 295 |
If element is pending and pending is an <{iframe}> 296 | element, then set element's iframe fullscreen flag. 297 | 298 |
Fullscreen element within doc. 299 | 300 |
Append (fullscreenchange, element) to
301 | doc's list of pending fullscreen events.
302 |
The order in which elements are fullscreened 305 | is not observable, because run the fullscreen steps is invoked in tree order. 306 | 307 |
Resolve promise with undefined. 308 |
Implementations with out-of-process browsing contexts are left as an 311 | exercise to the reader. Input welcome on potential improvements. 312 | 313 |
The fullscreenEnabled attribute's getter must
314 | return true if the context object is allowed to use the "fullscreen" feature and fullscreen is supported, and
316 | false otherwise.
317 |
318 |
The fullscreen attribute's getter must return
319 | false if context object's fullscreen element is null, and true otherwise.
320 |
321 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 322 | 323 |
The
324 | fullscreenElement
325 | attribute's getter must run these steps:
326 |
327 |
If the context object is a shadow root and its 329 | host is not connected, then return null.
Let candidate be the result of retargeting fullscreen element 332 | against the context object. 333 | 334 |
If candidate and the context object are in the same tree, then 335 | return candidate. 336 | 337 |
Return null. 338 |
A document is said to be a simple fullscreen document if there is exactly one 341 | element in its top layer that has its fullscreen flag set. 342 | 343 |
A document with two elements in its top layer can be a 344 | simple fullscreen document. For example, in addition to the fullscreen element there 345 | could be an open <{dialog}> element. 346 | 347 |
To collect documents to unfullscreen given doc, run these steps: 348 | 349 |
Let docs be an ordered set consisting of doc. 351 | 352 |
While true: 354 | 355 |
Let lastDoc be docs's last document. 357 | 358 |
Assert: lastDoc's fullscreen element is not null. 359 | 360 |
If lastDoc is not a simple fullscreen document, break. 361 | 362 |
Let container be lastDoc's browsing context container, if 363 | any, and otherwise break. 364 | 365 |
If container's iframe fullscreen flag is set, break. 366 | 367 |
Append container's node document to docs. 368 |
Return docs. 371 | 372 |
This is the set of documents for which the fullscreen element will be 373 | unfullscreened, but the last document in docs might 374 | have more than one element in its top layer with the fullscreen flag set, 375 | in which case that document will still remain in fullscreen. 376 |
To exit fullscreen a document doc, run these steps: 379 | 380 |
Let promise be a new promise. 382 | 383 |
If doc is not fully active or doc's fullscreen element
384 | is null, then reject promise with a TypeError exception and return
385 | promise.
386 |
387 |
Let resize be false. 388 | 389 |
Let docs be the result of 390 | collecting documents to unfullscreen given 391 | doc. 392 | 393 | 394 |
Let topLevelDoc be doc's top-level browsing context's 395 | active document. 396 | 397 | 398 |
If topLevelDoc is in docs, and it is a 399 | simple fullscreen document, then set doc to topLevelDoc and 400 | resize to true. 401 | 402 |
Return promise, and run the remaining steps in parallel. 403 | 404 |
If resize is true, resize doc's viewport to its "normal" dimensions. 405 | 406 |
If doc's fullscreen element is null, then resolve promise with 407 | undefined and terminate these steps. 408 | 409 |
Let exitDocs be the result of 410 | collecting documents to unfullscreen given 411 | doc. 412 | 413 | 414 |
Let descendantDocs be an ordered set consisting of doc's 415 | descendant browsing contexts' active documents whose fullscreen element is 416 | non-null, if any, in tree order. 417 | 418 | 419 |
For each exitDoc in exitDocs: 421 | 422 |
Append (fullscreenchange, exitDoc's
424 | fullscreen element) to exitDoc's list of pending fullscreen events.
425 |
426 |
If resize is true, unfullscreen 427 | exitDoc. 428 | 429 |
Otherwise, unfullscreen exitDoc's 430 | fullscreen element. 431 |
For each descendantDoc in descendantDocs: 435 | 436 |
Append (fullscreenchange, descendantDoc's
438 | fullscreen element) to descendantDoc's
439 | list of pending fullscreen events.
440 |
441 |
Unfullscreen descendantDoc. 442 |
The order in which documents are unfullscreened 445 | is not observable, because run the fullscreen steps is invoked in tree order. 446 | 447 |
Resolve promise with undefined. 448 |
The exitFullscreen() method, when invoked, must
451 | return the result of running exit fullscreen on the context object.
452 |
453 |
The following are the event handlers (and their corresponding 456 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 457 | event handler IDL attributes: 458 | 459 |
| event handler 463 | | event handler event type 464 | |
|---|---|
onfullscreenchange
467 | | fullscreenchange
468 | |
onfullscreenerror
470 | | fullscreenerror
471 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 474 | corresponding event handler content attributes for {{Element}} objects in any namespace. 475 | 476 | 477 | 478 |
User agents are encouraged to implement native media fullscreen controls in terms of 481 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 482 | 483 |
If the end user instructs the user agent to end a fullscreen session initiated via 484 | {{Element/requestFullscreen()}}, fully exit fullscreen the 485 | top-level browsing context's active document. 486 | 487 |
The user agent may end any fullscreen session without instruction from the end user 488 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 489 | 490 | 491 | 492 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 495 | 496 |
Long term CSS will define the top layer concept and its associated
497 | ::backdrop pseudo-element as part of CSS' stacking context model. Patching CSS
498 | as done here is sketchy as hell.
499 |
500 |
501 |
This specification introduces a new stacking layer to the 504 | Elaborate description of Stacking Contexts of CSS 505 | 2.1. It is called the top layer, comes after step 10 in the painting order, and is 506 | therefore rendered closest to the user within a viewport. Each document has one 507 | associated viewport and therefore also one top layer. [[!CSS]] 508 | 509 |
The terminology used in this and following subsection attempts to match CSS 2.1 510 | Appendix E. 511 | 512 |
The top layer is an ordered set of elements, rendered in the order they appear in 513 | the set. The last element in the set is rendered last, and thus appears on top. 514 | 515 |
The z-index property has no effect in the top layer.
516 |
517 |
Each element and ::backdrop pseudo-element in a top layer has the
518 | following characteristics:
519 |
520 |
It generates a new stacking context. 522 | 523 |
Its parent stacking context is the root stacking context. 524 | 525 |
If it consists of multiple layout boxes, the first box is used. 526 | 527 | 528 |
It is rendered as an atomic unit as if it were a sibling of its root. 530 | 531 |
Ancestor elements with overflow, opacity, masks, etc. cannot affect 532 | it. 533 | 534 |
If its position property computes to fixed, its containing block
535 | is the viewport, and the initial containing block otherwise.
536 |
537 |
If it is an element, it and its ::backdrop pseudo-element are not
538 | rendered if its shadow-including inclusive ancestor has the display property
539 | set to none.
540 |
541 |
If its specified display property is contents, it computes to
542 | block.
543 |
544 |
If its specified position property is not absolute or
545 | fixed, it computes to absolute.
546 |
547 |
Its outline, if any, is to be rendered before step 10 in the painting order. 548 | 549 |
Unless overridden by another specification, its static position for left,
550 | right, and top is zero.
551 |
To add an element to a top layer, 554 | remove it from top layer and then append it to 555 | top layer. 556 | 557 |
In other words, element is moved to the end of top layer if it 558 | is already present. 559 | 560 | 561 |
::backdrop pseudo-elementEach element in a top layer has a
564 | ::backdrop pseudo-element. This pseudo-element
565 | is a box rendered immediately below the element (and above the element before the element in the
566 | set, if any), within the same top layer.
567 |
568 |
The ::backdrop pseudo-element can be used to create a backdrop
569 | that hides the underlying document for an element in a top layer (such as an element that is
570 | displayed fullscreen).
571 |
572 |
It does not inherit from any element and is not inherited from. No restrictions are made on what 573 | properties apply to this pseudo-element either. 574 | 575 | 577 | 578 | 579 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
582 | element element for which one of the following conditions is true:
583 |
584 |
element's fullscreen flag is set. 586 | 587 |
element is a shadow host and the result of retargeting its 588 | node document's fullscreen element against element is element. 589 |
This makes it different from the 592 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 593 | 594 |
598 | @namespace "http://www.w3.org/1999/xhtml";
599 |
600 | *|*:not(:root):fullscreen {
601 | position:fixed !important;
602 | top:0 !important; right:0 !important; bottom:0 !important; left:0 !important;
603 | margin:0 !important;
604 | box-sizing:border-box !important;
605 | min-width:0 !important;
606 | max-width:none !important;
607 | min-height:0 !important;
608 | max-height:none !important;
609 | width:100% !important;
610 | height:100% !important;
611 | transform:none !important;
612 |
613 | /* intentionally not !important */
614 | object-fit:contain;
615 | }
616 |
617 | iframe:fullscreen {
618 | border:none !important;
619 | padding:0 !important;
620 | }
621 |
622 | ::backdrop {
623 | position:fixed;
624 | top:0; right:0; bottom:0; left:0;
625 | }
626 |
627 | *|*:not(:root):fullscreen::backdrop {
628 | background:black;
629 | }
630 |
631 |
632 |
633 |
634 | This specification defines a policy-controlled feature identified by the string
637 | "fullscreen". Its default allowlist is
638 | 'self'.
639 |
640 |
A document's feature policy determines whether any content in that document is allowed to 642 | go fullscreen. If disabled in any document, no content in the document will be allowed to use 643 | fullscreen. 644 | 645 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
646 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
647 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
648 | allow="fullscreen *">, as described in
649 | [[FEATURE-POLICY#iframe-allowfullscreen-attribute]].
650 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 656 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 657 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 658 | user agent or even operating system environment when fullscreen. See also the definition of 659 | {{Element/requestFullscreen()}}. 660 | 661 |
To enable content in a nested browsing context to go fullscreen, it needs to be
662 | specifically allowed via feature policy, either through the <{iframe/allowfullscreen}> attribute of
663 | the HTML <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the
664 | HTML <{iframe}> element, or through a `Feature-Policy` HTTP header
665 | delivered with the document through which it is nested.
666 |
667 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 668 | 669 | 670 | 671 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 674 | 675 | 676 |
Thanks to 677 | Andy Earnshaw, 678 | Chris Pearce, 679 | Darin Fisher, 680 | fantasai, 681 | Giuseppe Pascale, 682 | Glenn Maynard, 683 | Ian Clelland, 684 | Ian Hickson, 685 | Ignacio Solla, 686 | João Eiras, 687 | Josh Soref, 688 | Matt Falkenhagen, 689 | Mihai Balan, 690 | Mounir Lamouri, 691 | Øyvind Stenhaug, 692 | Pat Ladd, 693 | Rafał Chłodnicki, 694 | Riff Jiang, 695 | Rune Lillesveen, 696 | Sigbjørn Vik, 697 | Simon Pieters, 698 | Tab Atkins, 699 | Takayoshi Kochi, 700 | Theresa O'Connor, 701 | triple-underscore, 702 | Vincent Scheib, and 703 | Xidorn Quan 704 | for also being awesome. 705 | 706 |
This standard is edited by Philip Jägenstedt 707 | (Google, 708 | philip@foolip.org). It was originally written by 709 | Anne van Kesteren 710 | (Mozilla, 711 | annevk@annevk.nl). 712 | Tantek Çelik 713 | (Mozilla, 714 | tantek@cs.stanford.edu) sorted out legal hassles. 715 | -------------------------------------------------------------------------------- /review-drafts/2019-01.bs: -------------------------------------------------------------------------------- 1 |
2 | Group: WHATWG 3 | Date: 2019-01-23 4 | H1: Fullscreen API 5 | Shortname: fullscreen 6 | Text Macro: TWITTER fullscreenapi 7 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 8 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 9 | Markup Shorthands: css no 10 |11 | 12 |
13 | spec:dom 14 | type:dfn; for:/; text:element 15 | type:interface; text:Document 16 | spec:infra 17 | type:dfn; for:set; text:for each 18 | type:dfn; text:string 19 |20 | 21 |
22 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 23 | type: dfn 24 | text: triggered by a user generated orientation change 25 |26 | 27 |
28 | {
29 | "CSS": {
30 | "aliasOf": "CSS2"
31 | },
32 | "SVG": {
33 | "aliasOf": "SVG11"
34 | }
35 | }
36 |
37 |
38 |
39 |
40 | This specification depends on the Infra Standard. [[!INFRA]] 43 | 44 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 45 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 46 | 47 |
A browsing context A is called a descendant browsing context 48 | of a browsing context B if and only if B is an 49 | ancestor browsing context of A. 50 | 51 | 52 | 53 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 56 | unset. 57 | 58 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 59 | stated otherwise it is unset. 60 | 61 |
All documents have an associated fullscreen element. The 62 | fullscreen element is the topmost element in the document's 63 | top layer whose fullscreen flag is set, if any, and null otherwise. 64 | 65 |
All documents have an associated list of pending fullscreen events, which 66 | is an ordered set of (string, element) pairs. It is initially empty. 67 | 68 |
To fullscreen an element, set element's fullscreen flag 69 | and add it to its node document's top layer. 70 | 71 |
To unfullscreen an element, unset element's 72 | fullscreen flag and iframe fullscreen flag (if any), and remove it from 73 | its node document's top layer. 74 | 75 |
To unfullscreen a document, 76 | unfullscreen all elements, within document's 77 | top layer, whose fullscreen flag is set. 78 | 79 |
To fully exit fullscreen a document document, run these steps: 82 | 83 |
If document's fullscreen element is null, terminate these steps. 85 | 86 |
Unfullscreen elements whose fullscreen flag is 87 | set, within document's top layer, except for document's 88 | fullscreen element. 89 | 90 |
Exit fullscreen document. 91 |
Whenever the removing steps run with a removedNode, run 94 | these steps: 95 | 96 |
Let document be removedNode's node document. 98 | 99 |
Let nodes be removedNode's 100 | shadow-including inclusive descendants that have their fullscreen flag set, in 101 | shadow-including tree order. 102 | 103 |
For each node in nodes: 105 | 106 |
If node is document's fullscreen element, 108 | exit fullscreen document. 109 | 110 |
Otherwise, unfullscreen node. 111 | 112 |
If document's top layer contains node, 114 | remove node from document's top layer. 115 | 116 |
Other specifications can add and remove elements from top layer, so 117 | node might not be document's fullscreen element. For example, 118 | node could be an open <{dialog}> element. 119 |
Whenever the unloading document cleanup steps run with a document, 123 | fully exit fullscreen document. 124 | 125 |
Fullscreen is supported if there is no previously-established user preference, 128 | security risk, or platform limitation. 129 | 130 |
An algorithm is allowed to request fullscreen if one of the following is true: 131 | 132 |
The algorithm is triggered by user activation. 134 | 135 |
The algorithm is triggered by a user generated orientation change. 136 |
To run the fullscreen steps for a document document, run these 142 | steps: 143 | 144 |
Let pairs be document's list of pending fullscreen events. 146 | 147 |
Empty document's list of pending fullscreen events. 148 | 149 |
For each (type, element) in pairs: 151 | 152 |
Let target be element if element is connected 154 | and its node document is document, and otherwise let target be 155 | document. 156 | 157 |
Fire an event named type, with its {{Event/bubbles}} and 158 | {{Event/composed}} attributes set to true, at target. 159 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 163 | 164 | 165 | 166 |
169 | enum FullscreenNavigationUI {
170 | "auto",
171 | "show",
172 | "hide"
173 | };
174 |
175 | dictionary FullscreenOptions {
176 | FullscreenNavigationUI navigationUI = "auto";
177 | };
178 |
179 | partial interface Element {
180 | Promise<void> requestFullscreen(optional FullscreenOptions options);
181 |
182 | attribute EventHandler onfullscreenchange;
183 | attribute EventHandler onfullscreenerror;
184 | };
185 |
186 | partial interface Document {
187 | [LenientSetter] readonly attribute boolean fullscreenEnabled;
188 | [LenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
189 |
190 | Promise<void> exitFullscreen();
191 |
192 | attribute EventHandler onfullscreenchange;
193 | attribute EventHandler onfullscreenerror;
194 | };
195 |
196 | partial interface mixin DocumentOrShadowRoot {
197 | [LenientSetter] readonly attribute Element? fullscreenElement;
198 | };
199 |
200 |
202 |
203 | promise = element . requestFullscreen([options])
205 | navigationUI member indicates whether showing
209 | navigation UI while in fullscreen is preferred or not. If set to "show", navigation
210 | simplicity is preferred over screen space, and if set to "hide", more screen space
211 | is preferred. User agents are always free to honor user preference over the application's. The
212 | default value "auto" indicates no application preference.
213 |
214 | document . {{Document/fullscreenEnabled}}
215 | Returns true if document has the ability to display elements fullscreen 216 | and fullscreen is supported, or false otherwise. 217 | 218 |
promise = document . {{Document/exitFullscreen()}}
219 | Stops document's fullscreen element from being displayed fullscreen and 220 | resolves promise when done. 221 | 222 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
223 | Returns document's fullscreen element. 224 | 225 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
226 | Returns shadowroot's fullscreen element. 227 |
A fullscreen element ready check for an element element returns true 230 | if all of the following are true, and false otherwise: 231 | 232 |
element is connected. 234 | 235 |
element's node document is allowed to use the "fullscreen" feature.
237 |
238 |
The requestFullscreen(options) method,
241 | when invoked, must run these steps:
242 |
243 |
Let pending be the context object. 245 | 246 |
Let pendingDoc be pending's node document. 247 | 248 |
Let promise be a new promise. 249 | 250 |
If pendingDoc is not fully active, then reject promise with a
251 | TypeError exception and return promise.
252 |
253 |
Let error be false. 254 | 255 |
If any of the following conditions are false, then set error to true: 257 | 258 |
pending's namespace is the HTML namespace or
260 | pending is an
261 | SVG svg or
262 | MathML math
263 | element. [[!SVG]] [[!MATHML]]
264 |
265 |
pending is not a <{dialog}> element. 266 | 267 |
The fullscreen element ready check for pending returns true. 268 | 269 |
Fullscreen is supported. 270 | 271 |
This algorithm is allowed to request fullscreen. 272 |
Return promise, and run the remaining steps in parallel. 275 | 276 |
If error is false: Resize pendingDoc's
278 | top-level browsing context's active document's viewport's dimensions, optionally
279 | taking into account options's navigationUI member:
280 |
281 |
282 |
| value | 286 |viewport dimensions | 287 |
|---|---|
"hide" |
292 | full dimensions of the screen of the output device | 293 |
"show" |
296 | dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | 297 |
"auto" |
300 | user-agent defined, but matching one of the above | 301 |
Optionally display a message how the end user can revert this. 306 | 307 |
If any of the following conditions are false, then set error to true: 309 | 310 |
pending's node document is pendingDoc. 312 | 313 |
The fullscreen element ready check for pending returns true. 314 | 315 |
If error is true: 319 | 320 |
Append (fullscreenerror, pending) to
322 | pendingDoc's list of pending fullscreen events.
323 |
324 |
Reject promise with a TypeError exception and terminate these
325 | steps.
326 |
Let fullscreenElements be an ordered set initially consisting of 329 | pending. 330 | 331 |
While the first element in fullscreenElements is in a 332 | nested browsing context: append its browsing context container to 333 | fullscreenElements. 334 | 335 | 336 |
For each element in fullscreenElements: 338 | 339 |
Let doc be element's node document. 341 | 342 |
If element is doc's fullscreen element, continue. 344 | 345 |
No need to notify observers when nothing has changed. 346 | 347 |
If element is pending and pending is an <{iframe}> 348 | element, then set element's iframe fullscreen flag. 349 | 350 |
Fullscreen element within doc. 351 | 352 |
Append (fullscreenchange, element) to
353 | doc's list of pending fullscreen events.
354 |
The order in which elements are fullscreened 357 | is not observable, because run the fullscreen steps is invoked in tree order. 358 | 359 |
Resolve promise with undefined. 360 |
Implementations with out-of-process browsing contexts are left as an 363 | exercise to the reader. Input welcome on potential improvements. 364 | 365 |
The fullscreenEnabled attribute's getter must
366 | return true if the context object is allowed to use the "fullscreen" feature and fullscreen is supported, and
368 | false otherwise.
369 |
370 |
The fullscreen attribute's getter must return
371 | false if context object's fullscreen element is null, and true otherwise.
372 |
373 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 374 | 375 |
The
376 | fullscreenElement
377 | attribute's getter must run these steps:
378 |
379 |
If the context object is a shadow root and its 381 | host is not connected, then return null.
Let candidate be the result of retargeting fullscreen element 384 | against the context object. 385 | 386 |
If candidate and the context object are in the same tree, then 387 | return candidate. 388 | 389 |
Return null. 390 |
A document is said to be a simple fullscreen document if there is exactly one 393 | element in its top layer that has its fullscreen flag set. 394 | 395 |
A document with two elements in its top layer can be a 396 | simple fullscreen document. For example, in addition to the fullscreen element there 397 | could be an open <{dialog}> element. 398 | 399 |
To collect documents to unfullscreen given doc, run these steps: 400 | 401 |
Let docs be an ordered set consisting of doc. 403 | 404 |
While true: 406 | 407 |
Let lastDoc be docs's last document. 409 | 410 |
Assert: lastDoc's fullscreen element is not null. 411 | 412 |
If lastDoc is not a simple fullscreen document, break. 413 | 414 |
Let container be lastDoc's browsing context container, if 415 | any, and otherwise break. 416 | 417 |
If container's iframe fullscreen flag is set, break. 418 | 419 |
Append container's node document to docs. 420 |
Return docs. 423 | 424 |
This is the set of documents for which the fullscreen element will be 425 | unfullscreened, but the last document in docs might 426 | have more than one element in its top layer with the fullscreen flag set, 427 | in which case that document will still remain in fullscreen. 428 |
To exit fullscreen a document doc, run these steps: 431 | 432 |
Let promise be a new promise. 434 | 435 |
If doc is not fully active or doc's fullscreen element
436 | is null, then reject promise with a TypeError exception and return
437 | promise.
438 |
439 |
Let resize be false. 440 | 441 |
Let docs be the result of 442 | collecting documents to unfullscreen given 443 | doc. 444 | 445 | 446 |
Let topLevelDoc be doc's top-level browsing context's 447 | active document. 448 | 449 | 450 |
If topLevelDoc is in docs, and it is a 451 | simple fullscreen document, then set doc to topLevelDoc and 452 | resize to true. 453 | 454 |
If doc's fullscreen element is not connected: 455 |
Append (fullscreenchange, doc's
457 | fullscreen element) to doc's
458 | list of pending fullscreen events.
459 |
Return promise, and run the remaining steps in parallel. 462 | 463 |
If resize is true, resize doc's viewport to its "normal" dimensions. 464 | 465 |
If doc's fullscreen element is null, then resolve promise with 466 | undefined and terminate these steps. 467 | 468 |
Let exitDocs be the result of 469 | collecting documents to unfullscreen given 470 | doc. 471 | 472 | 473 |
Let descendantDocs be an ordered set consisting of doc's 474 | descendant browsing contexts' active documents whose fullscreen element is 475 | non-null, if any, in tree order. 476 | 477 | 478 |
For each exitDoc in exitDocs: 480 | 481 |
Append (fullscreenchange, exitDoc's
483 | fullscreen element) to exitDoc's list of pending fullscreen events.
484 |
485 |
If resize is true, unfullscreen 486 | exitDoc. 487 | 488 |
Otherwise, unfullscreen exitDoc's 489 | fullscreen element. 490 |
For each descendantDoc in descendantDocs: 494 | 495 |
Append (fullscreenchange, descendantDoc's
497 | fullscreen element) to descendantDoc's
498 | list of pending fullscreen events.
499 |
500 |
Unfullscreen descendantDoc. 501 |
The order in which documents are unfullscreened 504 | is not observable, because run the fullscreen steps is invoked in tree order. 505 | 506 |
Resolve promise with undefined. 507 |
The exitFullscreen() method, when invoked, must
510 | return the result of running exit fullscreen on the context object.
511 |
512 |
The following are the event handlers (and their corresponding 515 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 516 | event handler IDL attributes: 517 | 518 |
| event handler 522 | | event handler event type 523 | |
|---|---|
onfullscreenchange
526 | | fullscreenchange
527 | |
onfullscreenerror
529 | | fullscreenerror
530 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 533 | corresponding event handler content attributes for {{Element}} objects in any namespace. 534 | 535 | 536 | 537 |
User agents are encouraged to implement native media fullscreen controls in terms of 540 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 541 | 542 |
If the end user instructs the user agent to end a fullscreen session initiated via 543 | {{Element/requestFullscreen()}}, fully exit fullscreen the 544 | top-level browsing context's active document. 545 | 546 |
The user agent may end any fullscreen session without instruction from the end user 547 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 548 | 549 | 550 | 551 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 554 | 555 |
Long term CSS will define the top layer concept and its associated
556 | ::backdrop pseudo-element as part of CSS' stacking context model. Patching CSS
557 | as done here is sketchy as hell.
558 |
559 |
560 |
This specification introduces a new stacking layer to the 563 | Elaborate description of Stacking Contexts of CSS 564 | 2.1. It is called the top layer, comes after step 10 in the painting order, and is 565 | therefore rendered closest to the user within a viewport. Each document has one 566 | associated viewport and therefore also one top layer. [[!CSS]] 567 | 568 |
The terminology used in this and following subsection attempts to match CSS 2.1 569 | Appendix E. 570 | 571 |
The top layer is an ordered set of elements, rendered in the order they appear in 572 | the set. The last element in the set is rendered last, and thus appears on top. 573 | 574 |
The z-index property has no effect in the top layer.
575 |
576 |
Each element and ::backdrop pseudo-element in a top layer has the
577 | following characteristics:
578 |
579 |
It generates a new stacking context. 581 | 582 |
Its parent stacking context is the root stacking context. 583 | 584 |
If it consists of multiple layout boxes, the first box is used. 585 | 586 | 587 |
It is rendered as an atomic unit as if it were a sibling of its root. 589 | 590 |
Ancestor elements with overflow, opacity, masks, etc. cannot affect 591 | it. 592 | 593 |
If its position property computes to fixed, its containing block
594 | is the viewport, and the initial containing block otherwise.
595 |
596 |
If it is an element, it and its ::backdrop pseudo-element are not
597 | rendered if its shadow-including inclusive ancestor has the display property
598 | set to none.
599 |
600 |
If its specified display property is contents, it computes to
601 | block.
602 |
603 |
If its specified position property is not absolute or
604 | fixed, it computes to absolute.
605 |
606 |
Its outline, if any, is to be rendered before step 10 in the painting order. 607 | 608 |
Unless overridden by another specification, its static position for left,
609 | right, and top is zero.
610 |
To add an element to a top layer, 613 | remove it from top layer and then append it to 614 | top layer. 615 | 616 |
In other words, element is moved to the end of top layer if it 617 | is already present. 618 | 619 | 620 |
::backdrop pseudo-elementEach element in a top layer has a
623 | ::backdrop pseudo-element. This pseudo-element
624 | is a box rendered immediately below the element (and above the element before the element in the
625 | set, if any), within the same top layer.
626 |
627 |
The ::backdrop pseudo-element can be used to create a backdrop
628 | that hides the underlying document for an element in a top layer (such as an element that is
629 | displayed fullscreen).
630 |
631 |
It does not inherit from any element and is not inherited from. No restrictions are made on what 632 | properties apply to this pseudo-element either. 633 | 634 | 636 | 637 | 638 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
641 | element element for which one of the following conditions is true:
642 |
643 |
element's fullscreen flag is set. 645 | 646 |
element is a shadow host and the result of retargeting its 647 | node document's fullscreen element against element is element. 648 |
This makes it different from the 651 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 652 | 653 |
657 | @namespace "http://www.w3.org/1999/xhtml";
658 |
659 | *|*:not(:root):fullscreen {
660 | position:fixed !important;
661 | top:0 !important; right:0 !important; bottom:0 !important; left:0 !important;
662 | margin:0 !important;
663 | box-sizing:border-box !important;
664 | min-width:0 !important;
665 | max-width:none !important;
666 | min-height:0 !important;
667 | max-height:none !important;
668 | width:100% !important;
669 | height:100% !important;
670 | transform:none !important;
671 |
672 | /* intentionally not !important */
673 | object-fit:contain;
674 | }
675 |
676 | iframe:fullscreen {
677 | border:none !important;
678 | padding:0 !important;
679 | }
680 |
681 | ::backdrop {
682 | position:fixed;
683 | top:0; right:0; bottom:0; left:0;
684 | }
685 |
686 | *|*:not(:root):fullscreen::backdrop {
687 | background:black;
688 | }
689 |
690 |
691 |
692 |
693 | This specification defines a policy-controlled feature identified by the string
696 | "fullscreen". Its default allowlist is
697 | 'self'.
698 |
699 |
A document's feature policy determines whether any content in that document is allowed to 701 | go fullscreen. If disabled in any document, no content in the document will be allowed to use 702 | fullscreen. 703 | 704 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
705 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
706 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
707 | allow="fullscreen *">, as described in
708 | [[FEATURE-POLICY#iframe-allowfullscreen-attribute]].
709 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 715 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 716 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 717 | user agent or even operating system environment when fullscreen. See also the definition of 718 | {{Element/requestFullscreen()}}. 719 | 720 |
To enable content in a nested browsing context to go fullscreen, it needs to be
721 | specifically allowed via feature policy, either through the <{iframe/allowfullscreen}> attribute of
722 | the HTML <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the
723 | HTML <{iframe}> element, or through a `Feature-Policy` HTTP header
724 | delivered with the document through which it is nested.
725 |
726 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 727 | 728 | 729 | 730 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 733 | 734 | 735 |
Thanks to 736 | Andy Earnshaw, 737 | Chris Pearce, 738 | Darin Fisher, 739 | Dave Tapuska, 740 | fantasai, 741 | Giuseppe Pascale, 742 | Glenn Maynard, 743 | Ian Clelland, 744 | Ian Hickson, 745 | Ignacio Solla, 746 | João Eiras, 747 | Josh Soref, 748 | Kagami Sascha Rosylight, 749 | Matt Falkenhagen, 750 | Mihai Balan, 751 | Mounir Lamouri, 752 | Øyvind Stenhaug, 753 | Pat Ladd, 754 | Rafał Chłodnicki, 755 | Riff Jiang, 756 | Rune Lillesveen, 757 | Sigbjørn Vik, 758 | Simon Pieters, 759 | Tab Atkins, 760 | Takayoshi Kochi, 761 | Theresa O'Connor, 762 | triple-underscore, 763 | Vincent Scheib, and 764 | Xidorn Quan 765 | for also being awesome. 766 | 767 |
This standard is edited by Philip Jägenstedt 768 | (Google, 769 | philip@foolip.org). It was originally written by 770 | Anne van Kesteren 771 | (Mozilla, 772 | annevk@annevk.nl). 773 | Tantek Çelik 774 | (Mozilla, 775 | tantek@cs.stanford.edu) sorted out legal hassles. 776 | -------------------------------------------------------------------------------- /review-drafts/2020-01.bs: -------------------------------------------------------------------------------- 1 |
2 | Group: WHATWG 3 | Date: 2020-01-29 4 | H1: Fullscreen API 5 | Shortname: fullscreen 6 | Text Macro: TWITTER fullscreenapi 7 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 8 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 9 | Markup Shorthands: css no 10 |11 | 12 |
13 | spec:dom 14 | type:dfn; for:/; text:element 15 | type:interface; text:Document 16 | spec:infra 17 | type:dfn; for:set; text:for each 18 | type:dfn; text:string 19 |20 | 21 |
22 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 23 | type: dfn 24 | text: triggered by a user generated orientation change 25 |26 | 27 |
28 | {
29 | "CSS": {
30 | "aliasOf": "CSS2"
31 | },
32 | "SVG": {
33 | "aliasOf": "SVG11"
34 | }
35 | }
36 |
37 |
38 |
39 |
40 | This specification depends on the Infra Standard. [[!INFRA]] 43 | 44 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 45 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 46 | 47 |
A browsing context A is called a descendant browsing context 48 | of a browsing context B if and only if B is an 49 | ancestor browsing context of A. 50 | 51 | 52 | 53 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 56 | unset. 57 | 58 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 59 | stated otherwise it is unset. 60 | 61 |
All documents have an associated fullscreen element. The 62 | fullscreen element is the topmost element in the document's 63 | top layer whose fullscreen flag is set, if any, and null otherwise. 64 | 65 |
All documents have an associated list of pending fullscreen events, which 66 | is an ordered set of (string, element) pairs. It is initially empty. 67 | 68 |
To fullscreen an element, set element's fullscreen flag 69 | and add it to its node document's top layer. 70 | 71 |
To unfullscreen an element, unset element's 72 | fullscreen flag and iframe fullscreen flag (if any), and remove it from 73 | its node document's top layer. 74 | 75 |
To unfullscreen a document, 76 | unfullscreen all elements, within document's 77 | top layer, whose fullscreen flag is set. 78 | 79 |
To fully exit fullscreen a document document, run these steps: 82 | 83 |
If document's fullscreen element is null, terminate these steps. 85 | 86 |
Unfullscreen elements whose fullscreen flag is 87 | set, within document's top layer, except for document's 88 | fullscreen element. 89 | 90 |
Exit fullscreen document. 91 |
Whenever the removing steps run with a removedNode, run 94 | these steps: 95 | 96 |
Let document be removedNode's node document. 98 | 99 |
Let nodes be removedNode's 100 | shadow-including inclusive descendants that have their fullscreen flag set, in 101 | shadow-including tree order. 102 | 103 |
For each node in nodes: 105 | 106 |
If node is document's fullscreen element, 108 | exit fullscreen document. 109 | 110 |
Otherwise, unfullscreen node. 111 | 112 |
If document's top layer contains node, 114 | remove node from document's top layer. 115 | 116 |
Other specifications can add and remove elements from top layer, so 117 | node might not be document's fullscreen element. For example, 118 | node could be an open <{dialog}> element. 119 |
Whenever the unloading document cleanup steps run with a document, 123 | fully exit fullscreen document. 124 | 125 |
Fullscreen is supported if there is no previously-established user preference, 128 | security risk, or platform limitation. 129 | 130 |
To run the fullscreen steps for a document document, run these 133 | steps: 134 | 135 |
Let pairs be document's list of pending fullscreen events. 137 | 138 |
Empty document's list of pending fullscreen events. 139 | 140 |
For each (type, element) in pairs: 142 | 143 |
Let target be element if element is connected 145 | and its node document is document, and otherwise let target be 146 | document. 147 | 148 |
Fire an event named type, with its {{Event/bubbles}} and 149 | {{Event/composed}} attributes set to true, at target. 150 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 154 | 155 | 156 | 157 |
160 | enum FullscreenNavigationUI {
161 | "auto",
162 | "show",
163 | "hide"
164 | };
165 |
166 | dictionary FullscreenOptions {
167 | FullscreenNavigationUI navigationUI = "auto";
168 | };
169 |
170 | partial interface Element {
171 | Promise<void> requestFullscreen(optional FullscreenOptions options = {});
172 |
173 | attribute EventHandler onfullscreenchange;
174 | attribute EventHandler onfullscreenerror;
175 | };
176 |
177 | partial interface Document {
178 | [LenientSetter] readonly attribute boolean fullscreenEnabled;
179 | [LenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
180 |
181 | Promise<void> exitFullscreen();
182 |
183 | attribute EventHandler onfullscreenchange;
184 | attribute EventHandler onfullscreenerror;
185 | };
186 |
187 | partial interface mixin DocumentOrShadowRoot {
188 | [LenientSetter] readonly attribute Element? fullscreenElement;
189 | };
190 |
191 |
193 |
194 | promise = element . requestFullscreen([options])
196 | navigationUI member indicates whether showing
200 | navigation UI while in fullscreen is preferred or not. If set to "show", navigation
201 | simplicity is preferred over screen space, and if set to "hide", more screen space
202 | is preferred. User agents are always free to honor user preference over the application's. The
203 | default value "auto" indicates no application preference.
204 |
205 | document . {{Document/fullscreenEnabled}}
206 | Returns true if document has the ability to display elements fullscreen 207 | and fullscreen is supported, or false otherwise. 208 | 209 |
promise = document . {{Document/exitFullscreen()}}
210 | Stops document's fullscreen element from being displayed fullscreen and 211 | resolves promise when done. 212 | 213 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
214 | Returns document's fullscreen element. 215 | 216 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
217 | Returns shadowroot's fullscreen element. 218 |
A fullscreen element ready check for an element element returns true 221 | if all of the following are true, and false otherwise: 222 | 223 |
element is connected. 225 | 226 |
element's node document is allowed to use the "fullscreen" feature.
228 |
229 |
The requestFullscreen(options) method,
232 | when invoked, must run these steps:
233 |
234 |
Let pending be the context object. 236 | 237 |
Let pendingDoc be pending's node document. 238 | 239 |
Let promise be a new promise. 240 | 241 |
If pendingDoc is not fully active, then reject promise with a
242 | TypeError exception and return promise.
243 |
244 |
Let error be false. 245 | 246 |
If any of the following conditions are false, then set error to true: 248 | 249 |
pending's namespace is the HTML namespace or
251 | pending is an
252 | SVG svg or
253 | MathML math
254 | element. [[!SVG]] [[!MATHML]]
255 |
256 |
pending is not a <{dialog}> element. 257 | 258 |
The fullscreen element ready check for pending returns true. 259 | 260 |
Fullscreen is supported. 261 | 262 |
pending's relevant global object has transient activation or the 263 | algorithm is triggered by a user generated orientation change. 264 |
Return promise, and run the remaining steps in parallel. 267 | 268 |
If error is false, then resize pendingDoc's
270 | top-level browsing context's active document's viewport's dimensions, optionally
271 | taking into account options's navigationUI member:
272 |
273 |
274 |
| value | 278 |viewport dimensions | 279 |
|---|---|
"hide" |
284 | full dimensions of the screen of the output device | 285 |
"show" |
288 | dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | 289 |
"auto" |
292 | user-agent defined, but matching one of the above | 293 |
Optionally display a message how the end user can revert this. 298 | 299 |
If any of the following conditions are false, then set error to true: 301 | 302 |
pending's node document is pendingDoc. 304 | 305 |
The fullscreen element ready check for pending returns true. 306 | 307 |
If error is true: 311 | 312 |
Append (fullscreenerror, pending) to
314 | pendingDoc's list of pending fullscreen events.
315 |
316 |
Reject promise with a TypeError exception and terminate these
317 | steps.
318 |
Let fullscreenElements be an ordered set initially consisting of 321 | pending. 322 | 323 |
While the last element in fullscreenElements is in a 324 | nested browsing context: append its browsing context container to 325 | fullscreenElements. 326 | 327 | 328 |
For each element in fullscreenElements: 330 | 331 |
Let doc be element's node document. 333 | 334 |
If element is doc's fullscreen element, continue. 336 | 337 |
No need to notify observers when nothing has changed. 338 | 339 |
If element is pending and pending is an <{iframe}> 340 | element, then set element's iframe fullscreen flag. 341 | 342 |
Fullscreen element within doc. 343 | 344 |
Append (fullscreenchange, element) to
345 | doc's list of pending fullscreen events.
346 |
The order in which elements are fullscreened 349 | is not observable, because run the fullscreen steps is invoked in tree order. 350 | 351 |
Resolve promise with undefined. 352 |
Implementations with out-of-process browsing contexts are left as an 355 | exercise to the reader. Input welcome on potential improvements. 356 | 357 |
The fullscreenEnabled attribute's getter must
358 | return true if the context object is allowed to use the "fullscreen" feature and fullscreen is supported, and
360 | false otherwise.
361 |
362 |
The fullscreen attribute's getter must return
363 | false if context object's fullscreen element is null, and true otherwise.
364 |
365 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 366 | 367 |
The
368 | fullscreenElement
369 | attribute's getter must run these steps:
370 |
371 |
If the context object is a shadow root and its 373 | host is not connected, then return null.
Let candidate be the result of retargeting fullscreen element 376 | against the context object. 377 | 378 |
If candidate and the context object are in the same tree, then 379 | return candidate. 380 | 381 |
Return null. 382 |
A document is said to be a simple fullscreen document if there is exactly one 385 | element in its top layer that has its fullscreen flag set. 386 | 387 |
A document with two elements in its top layer can be a 388 | simple fullscreen document. For example, in addition to the fullscreen element there 389 | could be an open <{dialog}> element. 390 | 391 |
To collect documents to unfullscreen given doc, run these steps: 392 | 393 |
Let docs be an ordered set consisting of doc. 395 | 396 |
While true: 398 | 399 |
Let lastDoc be docs's last document. 401 | 402 |
Assert: lastDoc's fullscreen element is not null. 403 | 404 |
If lastDoc is not a simple fullscreen document, break. 405 | 406 |
Let container be lastDoc's browsing context container, if 407 | any, and otherwise break. 408 | 409 |
If container's iframe fullscreen flag is set, break. 410 | 411 |
Append container's node document to docs. 412 |
Return docs. 415 | 416 |
This is the set of documents for which the fullscreen element will be 417 | unfullscreened, but the last document in docs might 418 | have more than one element in its top layer with the fullscreen flag set, 419 | in which case that document will still remain in fullscreen. 420 |
To exit fullscreen a document doc, run these steps: 423 | 424 |
Let promise be a new promise. 426 | 427 |
If doc is not fully active or doc's fullscreen element
428 | is null, then reject promise with a TypeError exception and return
429 | promise.
430 |
431 |
Let resize be false. 432 | 433 |
Let docs be the result of 434 | collecting documents to unfullscreen given 435 | doc. 436 | 437 | 438 |
Let topLevelDoc be doc's top-level browsing context's 439 | active document. 440 | 441 | 442 |
If topLevelDoc is in docs, and it is a 443 | simple fullscreen document, then set doc to topLevelDoc and 444 | resize to true. 445 | 446 |
If doc's fullscreen element is not connected: 447 |
Append (fullscreenchange, doc's
449 | fullscreen element) to doc's
450 | list of pending fullscreen events.
451 |
Return promise, and run the remaining steps in parallel. 454 | 455 |
If resize is true, resize doc's viewport to its "normal" dimensions. 456 | 457 |
If doc's fullscreen element is null, then resolve promise with 458 | undefined and terminate these steps. 459 | 460 |
Let exitDocs be the result of 461 | collecting documents to unfullscreen given 462 | doc. 463 | 464 | 465 |
Let descendantDocs be an ordered set consisting of doc's 466 | descendant browsing contexts' active documents whose fullscreen element is 467 | non-null, if any, in tree order. 468 | 469 | 470 |
For each exitDoc in exitDocs: 472 | 473 |
Append (fullscreenchange, exitDoc's
475 | fullscreen element) to exitDoc's list of pending fullscreen events.
476 |
477 |
If resize is true, unfullscreen 478 | exitDoc. 479 | 480 |
Otherwise, unfullscreen exitDoc's 481 | fullscreen element. 482 |
For each descendantDoc in descendantDocs: 486 | 487 |
Append (fullscreenchange, descendantDoc's
489 | fullscreen element) to descendantDoc's
490 | list of pending fullscreen events.
491 |
492 |
Unfullscreen descendantDoc. 493 |
The order in which documents are unfullscreened 496 | is not observable, because run the fullscreen steps is invoked in tree order. 497 | 498 |
Resolve promise with undefined. 499 |
The exitFullscreen() method, when invoked, must
502 | return the result of running exit fullscreen on the context object.
503 |
504 |
The following are the event handlers (and their corresponding 507 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 508 | event handler IDL attributes: 509 | 510 |
| event handler 514 | | event handler event type 515 | |
|---|---|
onfullscreenchange
518 | | fullscreenchange
519 | |
onfullscreenerror
521 | | fullscreenerror
522 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 525 | corresponding event handler content attributes for {{Element}} objects in any namespace. 526 | 527 | 528 | 529 |
User agents are encouraged to implement native media fullscreen controls in terms of 532 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 533 | 534 |
If the end user instructs the user agent to end a fullscreen session initiated via 535 | {{Element/requestFullscreen()}}, fully exit fullscreen the 536 | top-level browsing context's active document. 537 | 538 |
The user agent may end any fullscreen session without instruction from the end user 539 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 540 | 541 | 542 | 543 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 546 | 547 |
Long term CSS will define the top layer concept and its associated
548 | ::backdrop pseudo-element as part of CSS' stacking context model. Patching CSS
549 | as done here is sketchy as hell.
550 |
551 |
552 |
This specification introduces a new stacking layer to the 555 | Elaborate description of Stacking Contexts of CSS 556 | 2.1. It is called the top layer, comes after step 10 in the painting order, and is 557 | therefore rendered closest to the user within a viewport. Each document has one 558 | associated viewport and therefore also one top layer. [[!CSS]] 559 | 560 |
The terminology used in this and following subsection attempts to match CSS 2.1 561 | Appendix E. 562 | 563 |
The top layer is an ordered set of elements, rendered in the order they appear in 564 | the set. The last element in the set is rendered last, and thus appears on top. 565 | 566 |
The z-index property has no effect in the top layer.
567 |
568 |
Each element and ::backdrop pseudo-element in a top layer has the
569 | following characteristics:
570 |
571 |
It generates a new stacking context. 573 | 574 |
Its parent stacking context is the root stacking context. 575 | 576 |
If it consists of multiple layout boxes, the first box is used. 577 | 578 | 579 |
It is rendered as an atomic unit as if it were a sibling of its root. 581 | 582 |
Ancestor elements with overflow, opacity, masks, etc. cannot affect 583 | it. 584 | 585 |
If its position property computes to fixed, its containing block
586 | is the viewport, and the initial containing block otherwise.
587 |
588 |
If it is an element, it and its ::backdrop pseudo-element are not
589 | rendered if its shadow-including inclusive ancestor has the display property
590 | set to none.
591 |
592 |
If its specified display property is contents, it computes to
593 | block.
594 |
595 |
If its specified position property is not absolute or
596 | fixed, it computes to absolute.
597 |
598 |
Its outline, if any, is to be rendered before step 10 in the painting order. 599 | 600 |
Unless overridden by another specification, its static position for left,
601 | right, and top is zero.
602 |
To add an element to a top layer, 605 | remove it from top layer and then append it to 606 | top layer. 607 | 608 |
In other words, element is moved to the end of top layer if it 609 | is already present. 610 | 611 | 612 |
::backdrop pseudo-elementEach element in a top layer has a
615 | ::backdrop pseudo-element. This pseudo-element
616 | is a box rendered immediately below the element (and above the element before the element in the
617 | set, if any), within the same top layer.
618 |
619 |
The ::backdrop pseudo-element can be used to create a backdrop
620 | that hides the underlying document for an element in a top layer (such as an element that is
621 | displayed fullscreen).
622 |
623 |
It does not inherit from any element and is not inherited from. No restrictions are made on what 624 | properties apply to this pseudo-element either. 625 | 626 | 628 | 629 | 630 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
633 | element element for which one of the following conditions is true:
634 |
635 |
element's fullscreen flag is set. 637 | 638 |
element is a shadow host and the result of retargeting its 639 | node document's fullscreen element against element is element. 640 |
This makes it different from the 643 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 644 | 645 |
649 | @namespace "http://www.w3.org/1999/xhtml";
650 |
651 | *|*:not(:root):fullscreen {
652 | position:fixed !important;
653 | top:0 !important; right:0 !important; bottom:0 !important; left:0 !important;
654 | margin:0 !important;
655 | box-sizing:border-box !important;
656 | min-width:0 !important;
657 | max-width:none !important;
658 | min-height:0 !important;
659 | max-height:none !important;
660 | width:100% !important;
661 | height:100% !important;
662 | transform:none !important;
663 |
664 | /* intentionally not !important */
665 | object-fit:contain;
666 | }
667 |
668 | iframe:fullscreen {
669 | border:none !important;
670 | padding:0 !important;
671 | }
672 |
673 | ::backdrop {
674 | position:fixed;
675 | top:0; right:0; bottom:0; left:0;
676 | }
677 |
678 | *|*:not(:root):fullscreen::backdrop {
679 | background:black;
680 | }
681 |
682 |
683 |
684 |
685 | This specification defines a policy-controlled feature identified by the string
688 | "fullscreen". Its default allowlist is
689 | 'self'.
690 |
691 |
A document's feature policy determines whether any content in that document is allowed to 693 | go fullscreen. If disabled in any document, no content in the document will be allowed to use 694 | fullscreen. 695 | 696 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
697 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
698 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
699 | allow="fullscreen *">, as described in
700 | [[FEATURE-POLICY#iframe-allowfullscreen-attribute]].
701 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 707 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 708 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 709 | user agent or even operating system environment when fullscreen. See also the definition of 710 | {{Element/requestFullscreen()}}. 711 | 712 |
To enable content in a nested browsing context to go fullscreen, it needs to be
713 | specifically allowed via feature policy, either through the <{iframe/allowfullscreen}> attribute of
714 | the HTML <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the
715 | HTML <{iframe}> element, or through a `Feature-Policy` HTTP header
716 | delivered with the document through which it is nested.
717 |
718 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 719 | 720 | 721 | 722 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 725 | 726 | 727 |
Thanks to 728 | Andy Earnshaw, 729 | Changwan Hong, 730 | Chris Pearce, 731 | Darin Fisher, 732 | Dave Tapuska, 733 | fantasai, 734 | Giuseppe Pascale, 735 | Glenn Maynard, 736 | Ian Clelland, 737 | Ian Hickson, 738 | Ignacio Solla, 739 | João Eiras, 740 | Josh Soref, 741 | Kagami Sascha Rosylight, 742 | Matt Falkenhagen, 743 | Mihai Balan, 744 | Mounir Lamouri, 745 | Øyvind Stenhaug, 746 | Pat Ladd, 747 | Rafał Chłodnicki, 748 | Riff Jiang, 749 | Rune Lillesveen, 750 | Sigbjørn Vik, 751 | Simon Pieters, 752 | Tab Atkins, 753 | Takayoshi Kochi, 754 | Theresa O'Connor, 755 | triple-underscore, 756 | Vincent Scheib, and 757 | Xidorn Quan 758 | for also being awesome. 759 | 760 |
This standard is edited by Philip Jägenstedt 761 | (Google, 762 | philip@foolip.org). It was originally written by 763 | Anne van Kesteren 764 | (Mozilla, 765 | annevk@annevk.nl). 766 | Tantek Çelik 767 | (Mozilla, 768 | tantek@cs.stanford.edu) sorted out legal hassles. 769 | -------------------------------------------------------------------------------- /review-drafts/2023-07.bs: -------------------------------------------------------------------------------- 1 |
2 | Group: WHATWG 3 | Status: RD 4 | Date: 2023-07-17 5 | H1: Fullscreen API 6 | Shortname: fullscreen 7 | Text Macro: TWITTER fullscreenapi 8 | Text Macro: LATESTRD 2023-07 9 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 10 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 11 | Markup Shorthands: css no 12 |13 | 14 |
15 | spec:dom 16 | type:dfn; for:/; text:element 17 | type:interface; text:Document 18 | spec:infra 19 | type:dfn; for:set; text:for each 20 | type:dfn; text:string 21 | spec:css-position-4 22 | type:selector; text: ::backdrop 23 | type:dfn; text:top layer 24 |25 | 26 |
27 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 28 | type: dfn 29 | text: triggered by a user generated orientation change 30 |31 | 32 |
33 | {
34 | "CSS": {
35 | "aliasOf": "CSS2"
36 | },
37 | "SVG": {
38 | "aliasOf": "SVG11"
39 | }
40 | }
41 |
42 |
43 |
44 |
45 | This specification depends on the Infra Standard. [[!INFRA]] 48 | 49 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 50 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 51 | 52 | 53 | 54 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 57 | unset. 58 | 59 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 60 | stated otherwise it is unset. 61 | 62 |
All documents have an associated fullscreen element. The 63 | fullscreen element is the topmost element in the document's 64 | top layer whose fullscreen flag is set, if any, and null otherwise. 65 | 66 |
All documents have an associated list of pending fullscreen events, which 67 | is an ordered set of (string, element) tuples. It is initially empty. 68 | 69 |
To fullscreen an element: 70 | 71 |
Run hide all popovers given element's node document. 73 | 74 |
Set element's fullscreen flag. 75 | 76 |
Remove from the top layer immediately given element. 77 | 78 |
To unfullscreen an element, unset element's 82 | fullscreen flag and iframe fullscreen flag (if any), and 83 | remove from the top layer immediately given element. 84 | 85 |
To unfullscreen a document, 86 | unfullscreen all elements, within document's 87 | top layer, whose fullscreen flag is set. 88 | 89 |
To fully exit fullscreen a document document, run these steps: 93 | 94 |
If document's fullscreen element is null, terminate these steps. 96 | 97 |
Unfullscreen elements whose fullscreen flag is 98 | set, within document's top layer, except for document's 99 | fullscreen element. 100 | 101 |
Exit fullscreen document. 102 |
Whenever the removing steps run with a removedNode, run 107 | these steps: 108 | 109 |
Let document be removedNode's node document. 111 | 112 |
Let nodes be removedNode's 113 | shadow-including inclusive descendants that have their fullscreen flag set, in 114 | shadow-including tree order. 115 | 116 |
For each node in nodes: 118 | 119 |
If node is document's fullscreen element, 121 | exit fullscreen document. 122 | 123 |
Otherwise, unfullscreen node. 124 | 125 |
If document's top layer contains node, 127 | remove from the top layer immediately given node. 128 | 129 |
Other specifications can add and remove elements from top layer, so 130 | node might not be document's fullscreen element. For example, 131 | node could be an open <{dialog}> element. 132 |
Whenever the unloading document cleanup steps run with a document, 137 | fully exit fullscreen document. 138 | 139 |
Fullscreen is supported if there is no previously-established user preference, 142 | security risk, or platform limitation. 143 | 144 |
To run the fullscreen steps for a document document, run these 148 | steps: 149 | 150 |
Let pendingEvents be document's 152 | list of pending fullscreen events. 153 | 154 |
Empty document's list of pending fullscreen events. 155 | 156 |
For each (type, element) in pendingEvents: 158 | 159 |
Let target be element if element is connected 161 | and its node document is document, and otherwise let target be 162 | document. 163 | 164 |
Fire an event named type, with its {{Event/bubbles}} and 165 | {{Event/composed}} attributes set to true, at target. 166 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 170 |
177 | enum FullscreenNavigationUI {
178 | "auto",
179 | "show",
180 | "hide"
181 | };
182 |
183 | dictionary FullscreenOptions {
184 | FullscreenNavigationUI navigationUI = "auto";
185 | };
186 |
187 | partial interface Element {
188 | Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});
189 |
190 | attribute EventHandler onfullscreenchange;
191 | attribute EventHandler onfullscreenerror;
192 | };
193 |
194 | partial interface Document {
195 | [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
196 | [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
197 |
198 | Promise<undefined> exitFullscreen();
199 |
200 | attribute EventHandler onfullscreenchange;
201 | attribute EventHandler onfullscreenerror;
202 | };
203 |
204 | partial interface mixin DocumentOrShadowRoot {
205 | [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
206 | };
207 |
208 |
210 |
211 | promise = element . requestFullscreen([options])
213 | document . {{Document/fullscreenEnabled}}
224 | Returns true if document has the ability to display elements fullscreen 225 | and fullscreen is supported, or false otherwise. 226 | 227 |
promise = document . {{Document/exitFullscreen()}}
228 | Stops document's fullscreen element from being displayed fullscreen and 229 | resolves promise when done. 230 | 231 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
232 | Returns document's fullscreen element. 233 | 234 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
235 | Returns shadowroot's fullscreen element. 236 |
A fullscreen element ready check for an element element returns true 239 | if all of the following are true, and false otherwise: 240 | 241 |
element is connected. 243 | 244 |
element's node document is allowed to use the "fullscreen" feature.
246 |
247 |
248 |
element namespace is not the HTML namespace or 249 | element's popover visibility state is hidden. 251 |
The requestFullscreen(options) method steps
255 | are:
256 |
257 |
Let pendingDoc be this's node document. 259 | 260 |
Let promise be a new promise. 261 | 262 |
If pendingDoc is not fully active, then reject promise with a 263 | {{TypeError}} exception and return promise. 264 | 265 |
Let error be false. 266 | 267 |
If any of the following conditions are false, then set error to true: 269 | 270 |
This's namespace is the HTML namespace or
272 | this is an
273 | SVG svg or
274 | MathML math
275 | element. [[!SVG]] [[!MATHML]]
276 |
277 |
This is not a <{dialog}> element. 278 | 279 |
The fullscreen element ready check for this returns true. 280 | 281 |
Fullscreen is supported. 282 | 283 |
This's relevant global object has transient activation or the 284 | algorithm is triggered by a user generated orientation change. 285 |
If error is false, then consume user activation given 288 | pendingDoc's relevant global object. 289 | 290 |
Return promise, and run the remaining steps in parallel. 291 | 292 |
If error is false, then resize pendingDoc's node navigable's 294 | top-level traversable's active document's viewport's 295 | dimensions, optionally taking into account 296 | options["{{FullscreenOptions/navigationUI}}"]: 297 | 298 | 299 |
| value | 303 |viewport dimensions | 304 |
|---|---|
"hide" |
309 | full dimensions of the screen of the output device | 310 |
"show" |
313 | dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | 314 |
"auto" |
317 | user-agent defined, but matching one of the above | 318 |
Optionally display a message how the end user can revert this. 323 | 324 |
If any of the following conditions are false, then set error to true: 326 | 327 |
This's node document is pendingDoc. 329 | 330 |
The fullscreen element ready check for this returns true. 331 | 332 |
If error is true: 336 | 337 |
Append ({{fullscreenerror}}, this) to 339 | pendingDoc's list of pending fullscreen events. 340 | 341 |
Reject promise with a {{TypeError}} exception and terminate these 342 | steps. 343 |
Let fullscreenElements be an ordered set initially consisting of 346 | this. 347 | 348 |
While true: 350 | 351 |
Let last be the last item of fullscreenElements. 353 | 354 |
Let container be last's node navigable's 355 | container. 356 | 357 |
If container is null, then break. 358 | 359 |
Append container to fullscreenElements. 360 |
For each element in fullscreenElements: 366 | 367 |
Let doc be element's node document. 369 | 370 |
If element is doc's fullscreen element, continue. 372 | 373 |
No need to notify observers when nothing has changed. 374 | 375 |
If element is this and this is an <{iframe}> 376 | element, then set element's iframe fullscreen flag. 377 | 378 |
Fullscreen element within doc. 379 | 380 |
Append ({{fullscreenchange}}, element) to 381 | doc's list of pending fullscreen events. 382 |
The order in which elements are fullscreened 385 | is not observable, because run the fullscreen steps is invoked in tree order. 386 | 387 |
Resolve promise with undefined. 388 |
Implementations with out-of-process navigables are left as an exercise 391 | to the reader. Input welcome on potential improvements. 392 |
The fullscreenEnabled getter steps are to return
395 | true if this is allowed to use the "fullscreen" feature and fullscreen is supported, and
397 | false otherwise.
398 |
399 |
The fullscreen getter steps are to return false if
400 | this's fullscreen element is null, and true otherwise.
401 |
402 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 403 | 404 |
The
406 | fullscreenElement
407 | getter steps are:
408 |
409 |
If this is a shadow root and its host is not 411 | connected, then return null. 412 | 413 |
Let candidate be the result of retargeting fullscreen element 414 | against this. 415 | 416 |
If candidate and this are in the same tree, then return 417 | candidate. 418 | 419 |
Return null. 420 |
A document is said to be a simple fullscreen document if there is exactly one 424 | element in its top layer that has its fullscreen flag set. 425 | 426 |
A document with two elements in its top layer can be a 427 | simple fullscreen document. For example, in addition to the fullscreen element there 428 | could be an open <{dialog}> element. 429 | 430 |
To collect documents to unfullscreen given doc, run these steps: 432 | 433 |
Let docs be an ordered set consisting of doc. 435 | 436 |
While true: 438 | 439 |
Let lastDoc be docs's last document. 441 | 442 |
Assert: lastDoc's fullscreen element is not null. 443 | 444 |
If lastDoc is not a simple fullscreen document, break. 445 | 446 |
Let container be lastDoc's node navigable's 447 | container. 448 | 449 |
If container is null, then break. 450 | 451 |
If container's iframe fullscreen flag is set, break. 452 | 453 |
Append container's node document to docs. 454 |
Return docs. 457 | 458 |
This is the set of documents for which the fullscreen element will be 459 | unfullscreened, but the last document in docs might 460 | have more than one element in its top layer with the fullscreen flag set, 461 | in which case that document will still remain in fullscreen. 462 |
To exit fullscreen a document doc, run these steps: 467 | 468 |
Let promise be a new promise. 470 | 471 |
If doc is not fully active or doc's fullscreen element 472 | is null, then reject promise with a {{TypeError}} exception and return 473 | promise. 474 | 475 |
Let resize be false. 476 | 477 |
Let docs be the result of 478 | collecting documents to unfullscreen given 479 | doc. 480 | 481 | 482 |
Let topLevelDoc be doc's node navigable's 483 | top-level traversable's active document. 484 | 485 | 486 |
If topLevelDoc is in docs, and it is a 487 | simple fullscreen document, then set doc to topLevelDoc and 488 | resize to true. 489 | 490 |
If doc's fullscreen element is not connected: 491 |
Append ({{fullscreenchange}}, doc's 493 | fullscreen element) to doc's 494 | list of pending fullscreen events. 495 |
Return promise, and run the remaining steps in parallel. 498 | 499 |
Run the [=fully unlock the screen orientation steps=] with doc. 500 | 501 |
If resize is true, resize doc's viewport to its "normal" dimensions. 502 | 503 |
If doc's fullscreen element is null, then resolve promise with 504 | undefined and terminate these steps. 505 | 506 |
Let exitDocs be the result of 507 | collecting documents to unfullscreen given 508 | doc. 509 | 510 | 511 |
Let descendantDocs be an ordered set consisting of doc's 512 | descendant navigables' active documents whose 513 | fullscreen element is non-null, if any, in tree order. 514 | 515 | 516 |
For each exitDoc in exitDocs: 518 | 519 |
Append ({{fullscreenchange}}, exitDoc's 521 | fullscreen element) to exitDoc's list of pending fullscreen events. 522 | 523 |
If resize is true, unfullscreen 524 | exitDoc. 525 | 526 |
Otherwise, unfullscreen exitDoc's 527 | fullscreen element. 528 |
For each descendantDoc in descendantDocs: 532 | 533 |
Append ({{fullscreenchange}}, descendantDoc's 535 | fullscreen element) to descendantDoc's 536 | list of pending fullscreen events. 537 | 538 |
Unfullscreen descendantDoc. 539 |
The order in which documents are unfullscreened 542 | is not observable, because run the fullscreen steps is invoked in tree order. 543 | 544 |
Resolve promise with undefined. 545 |
The exitFullscreen() method steps are to return the
549 | result of running exit fullscreen on this.
550 |
551 |
The following are the event handlers (and their corresponding 554 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 555 | event handler IDL attributes: 556 | 557 |
| event handler 561 | | event handler event type 562 | |
|---|---|
onfullscreenchange
565 | | fullscreenchange
566 | |
onfullscreenerror
568 | | fullscreenerror
569 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 572 | corresponding event handler content attributes for {{Element}} objects in any namespace. 573 | 574 | 575 | 576 |
User agents are encouraged to implement native media fullscreen controls in terms of 579 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 580 | 581 |
If the end user instructs the user agent to end a fullscreen session initiated via 582 | {{Element/requestFullscreen()}}, fully exit fullscreen given the 583 | top-level traversable's active document. 584 | 585 |
The user agent may end any fullscreen session without instruction from the end user 586 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 587 | 588 | 589 | 590 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 593 | 594 | 595 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
598 | element element for which one of the following conditions is true:
599 |
600 |
element's fullscreen flag is set. 602 | 603 |
element is a shadow host and the result of retargeting its 604 | node document's fullscreen element against element is element. 605 |
This makes it different from the 608 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 609 | 610 |
614 | @namespace "http://www.w3.org/1999/xhtml";
615 |
616 | *|*:not(:root):fullscreen {
617 | position:fixed !important;
618 | inset:0 !important;
619 | margin:0 !important;
620 | box-sizing:border-box !important;
621 | min-width:0 !important;
622 | max-width:none !important;
623 | min-height:0 !important;
624 | max-height:none !important;
625 | width:100% !important;
626 | height:100% !important;
627 | transform:none !important;
628 |
629 | /* intentionally not !important */
630 | object-fit:contain;
631 | }
632 |
633 | iframe:fullscreen {
634 | border:none !important;
635 | padding:0 !important;
636 | }
637 |
638 | *|*:not(:root):fullscreen::backdrop {
639 | background:black;
640 | }
641 |
642 |
643 |
644 |
645 | This specification defines a policy-controlled feature identified by the string
649 | "fullscreen". Its default allowlist is
650 | 'self'.
651 |
652 |
A document's permissions policy determines whether any content in that 654 | document is allowed to go fullscreen. If disabled in any document, no content in the document will 655 | be allowed to use fullscreen. 656 | 657 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
658 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
659 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
660 | allow="fullscreen *">, as described in
661 | [[permissions-policy#iframe-allowfullscreen-attribute]].
662 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 669 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 670 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 671 | user agent or even operating system environment when fullscreen. See also the definition of 672 | {{Element/requestFullscreen()}}. 673 | 674 |
To enable content in a child navigable to go fullscreen, it needs to be specifically
675 | allowed via permissions policy, either through the <{iframe/allowfullscreen}> attribute of the HTML
676 | <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the HTML
677 | <{iframe}> element, or through a `Permissions-Policy` HTTP header
678 | delivered with the document through which it is nested.
679 |
680 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 681 | 682 | 683 | 684 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 694 | 695 | 696 |
Thanks to 697 | Andy Earnshaw, 698 | Changwan Hong, 699 | Chris Pearce, 700 | Darin Fisher, 701 | Dave Tapuska, 702 | fantasai, 703 | Giuseppe Pascale, 704 | Glenn Maynard, 705 | Ian Clelland, 706 | Ian Hickson, 707 | Ignacio Solla, 708 | João Eiras, 709 | Josh Soref, 710 | Kagami Sascha Rosylight, 711 | Matt Falkenhagen, 712 | Mihai Balan, 713 | Mounir Lamouri, 714 | Øyvind Stenhaug, 715 | Pat Ladd, 716 | Rafał Chłodnicki, 717 | Riff Jiang, 718 | Rune Lillesveen, 719 | Sigbjørn Vik, 720 | Simon Pieters, 721 | Tab Atkins-Bittner, 722 | Takayoshi Kochi, 723 | Theresa O'Connor, 724 | triple-underscore, 725 | Vincent Scheib, and 726 | Xidorn Quan 727 | for also being awesome. 728 | 729 |
This standard is edited by Philip Jägenstedt 730 | (Google, 731 | philip@foolip.org). It was originally written by 732 | Anne van Kesteren 733 | (Apple, annevk@annevk.nl). 734 | Tantek Çelik 735 | (Mozilla, 736 | tantek@cs.stanford.edu) sorted out legal hassles. 737 | -------------------------------------------------------------------------------- /review-drafts/2024-07.bs: -------------------------------------------------------------------------------- 1 |
2 | Group: WHATWG 3 | Status: RD 4 | Date: 2024-07-15 5 | H1: Fullscreen API 6 | Shortname: fullscreen 7 | Text Macro: TWITTER fullscreenapi 8 | Text Macro: LATESTRD 2024-07 9 | Abstract: The Fullscreen API standard defines an API for elements to display themselves fullscreen. 10 | Translation: ja https://triple-underscore.github.io/fullscreen-ja.html 11 | Markup Shorthands: css no 12 |13 | 14 |
15 | spec:dom 16 | type:dfn; for:/; text:element 17 | type:interface; text:Document 18 | spec:infra 19 | type:dfn; for:set; text:for each 20 | type:dfn; text:string 21 | spec:css-position-4 22 | type:selector; text: ::backdrop 23 | type:dfn; text:top layer 24 |25 | 26 |
27 | urlPrefix: https://w3c.github.io/screen-orientation/#dfn- 28 | type: dfn 29 | text: triggered by a user generated orientation change 30 |31 | 32 |
33 | {
34 | "CSS": {
35 | "aliasOf": "CSS2"
36 | },
37 | "SVG": {
38 | "aliasOf": "SVG11"
39 | }
40 | }
41 |
42 |
43 |
44 |
45 | This specification depends on the Infra Standard. [[!INFRA]] 48 | 49 |
Most terminology used in this specification is from CSS, DOM, HTML, and Web IDL. [[!CSS]] 50 | [[!DOM]] [[!HTML]] [[!WEBIDL]] 51 | 52 | 53 | 54 |
All elements have an associated fullscreen flag. Unless stated otherwise it is 57 | unset. 58 | 59 |
All <{iframe}> elements have an associated iframe fullscreen flag. Unless 60 | stated otherwise it is unset. 61 | 62 |
All documents have an associated fullscreen element. The 63 | fullscreen element is the topmost element in the document's 64 | top layer whose fullscreen flag is set, if any, and null otherwise. 65 | 66 |
All documents have an associated list of pending fullscreen events, which 67 | is an ordered set of (string, element) tuples. It is initially empty. 68 | 69 |
To fullscreen an element: 70 | 71 |
Let hideUntil be the result of running topmost popover ancestor given 73 | element, null, and false. 74 | 75 |
If hideUntil is null, then set hideUntil to element's 76 | node document. 77 | 78 |
Run hide all popovers until given hideUntil, false, and true. 79 | 80 |
Set element's fullscreen flag. 81 | 82 |
Remove from the top layer immediately given element. 83 | 84 |
To unfullscreen an element, unset element's 88 | fullscreen flag and iframe fullscreen flag (if any), and 89 | remove from the top layer immediately given element. 90 | 91 |
To unfullscreen a document, 92 | unfullscreen all elements, within document's 93 | top layer, whose fullscreen flag is set. 94 | 95 |
To fully exit fullscreen a document document, run these steps: 99 | 100 |
If document's fullscreen element is null, terminate these steps. 102 | 103 |
Unfullscreen elements whose fullscreen flag is 104 | set, within document's top layer, except for document's 105 | fullscreen element. 106 | 107 |
Exit fullscreen document. 108 |
Whenever the removing steps run with a removedNode, run 113 | these steps: 114 | 115 |
Let document be removedNode's node document. 117 | 118 |
Let nodes be removedNode's 119 | shadow-including inclusive descendants that have their fullscreen flag set, in 120 | shadow-including tree order. 121 | 122 |
For each node in nodes: 124 | 125 |
If node is document's fullscreen element, 127 | exit fullscreen document. 128 | 129 |
Otherwise, unfullscreen node. 130 | 131 |
If document's top layer contains node, 133 | remove from the top layer immediately given node. 134 | 135 |
Other specifications can add and remove elements from top layer, so 136 | node might not be document's fullscreen element. For example, 137 | node could be an open <{dialog}> element. 138 |
Whenever the unloading document cleanup steps run with a document, 143 | fully exit fullscreen document. 144 | 145 |
Fullscreen is supported if there is no previously-established user preference, 148 | security risk, or platform limitation. 149 | 150 |
To run the fullscreen steps for a document document, run these 154 | steps: 155 | 156 |
Let pendingEvents be document's 158 | list of pending fullscreen events. 159 | 160 |
Empty document's list of pending fullscreen events. 161 | 162 |
For each (type, element) in pendingEvents: 164 | 165 |
Let target be element if element is connected 167 | and its node document is document, and otherwise let target be 168 | document. 169 | 170 |
Fire an event named type, with its {{Event/bubbles}} and 171 | {{Event/composed}} attributes set to true, at target. 172 |
These steps integrate with the event loop defined in HTML. [[!HTML]] 176 |
183 | enum FullscreenNavigationUI {
184 | "auto",
185 | "show",
186 | "hide"
187 | };
188 |
189 | dictionary FullscreenOptions {
190 | FullscreenNavigationUI navigationUI = "auto";
191 | };
192 |
193 | partial interface Element {
194 | Promise<undefined> requestFullscreen(optional FullscreenOptions options = {});
195 |
196 | attribute EventHandler onfullscreenchange;
197 | attribute EventHandler onfullscreenerror;
198 | };
199 |
200 | partial interface Document {
201 | [LegacyLenientSetter] readonly attribute boolean fullscreenEnabled;
202 | [LegacyLenientSetter, Unscopable] readonly attribute boolean fullscreen; // historical
203 |
204 | Promise<undefined> exitFullscreen();
205 |
206 | attribute EventHandler onfullscreenchange;
207 | attribute EventHandler onfullscreenerror;
208 | };
209 |
210 | partial interface mixin DocumentOrShadowRoot {
211 | [LegacyLenientSetter] readonly attribute Element? fullscreenElement;
212 | };
213 |
214 |
216 |
217 | promise = element . requestFullscreen([options])
219 | document . {{Document/fullscreenEnabled}}
230 | Returns true if document has the ability to display elements fullscreen 231 | and fullscreen is supported, or false otherwise. 232 | 233 |
promise = document . {{Document/exitFullscreen()}}
234 | Stops document's fullscreen element from being displayed fullscreen and 235 | resolves promise when done. 236 | 237 |
document . {{DocumentOrShadowRoot/fullscreenElement}}
238 | Returns document's fullscreen element. 239 | 240 |
shadowroot . {{DocumentOrShadowRoot/fullscreenElement}}
241 | Returns shadowroot's fullscreen element. 242 |
A fullscreen element ready check for an element element returns true 245 | if all of the following are true, and false otherwise: 246 | 247 |
element is connected. 249 | 250 |
element's node document is allowed to use the "fullscreen" feature.
252 |
253 |
254 |
element namespace is not the HTML namespace or 255 | element's popover visibility state is hidden. 257 |
The requestFullscreen(options) method steps
261 | are:
262 |
263 |
Let pendingDoc be this's node document. 265 | 266 |
Let promise be a new promise. 267 | 268 |
If pendingDoc is not fully active, then reject promise with a 269 | {{TypeError}} exception and return promise. 270 | 271 |
Let error be false. 272 | 273 |
If any of the following conditions are false, then set error to true: 275 | 276 |
This's namespace is the HTML namespace or
278 | this is an
279 | SVG svg or
280 | MathML math
281 | element. [[!SVG]] [[!MATHML]]
282 |
283 |
This is not a <{dialog}> element. 284 | 285 |
The fullscreen element ready check for this returns true. 286 | 287 |
Fullscreen is supported. 288 | 289 |
This's relevant global object has transient activation or the 290 | algorithm is triggered by a user generated orientation change. 291 |
If error is false, then consume user activation given 294 | pendingDoc's relevant global object. 295 | 296 |
Return promise, and run the remaining steps in parallel. 297 | 298 |
If error is false, then resize pendingDoc's node navigable's 300 | top-level traversable's active document's viewport's 301 | dimensions, optionally taking into account 302 | options["{{FullscreenOptions/navigationUI}}"]: 303 | 304 | 305 |
| value | 309 |viewport dimensions | 310 |
|---|---|
"hide" |
315 | full dimensions of the screen of the output device | 316 |
"show" |
319 | dimensions of the screen of the output device clamped to allow the user agent to show page navigation controls | 320 |
"auto" |
323 | user-agent defined, but matching one of the above | 324 |
Optionally display a message how the end user can revert this. 329 | 330 |
If any of the following conditions are false, then set error to true: 332 | 333 |
This's node document is pendingDoc. 335 | 336 |
The fullscreen element ready check for this returns true. 337 | 338 |
If error is true: 342 | 343 |
Append ({{fullscreenerror}}, this) to 345 | pendingDoc's list of pending fullscreen events. 346 | 347 |
Reject promise with a {{TypeError}} exception and terminate these 348 | steps. 349 |
Let fullscreenElements be an ordered set initially consisting of 352 | this. 353 | 354 |
While true: 356 | 357 |
Let last be the last item of fullscreenElements. 359 | 360 |
Let container be last's node navigable's 361 | container. 362 | 363 |
If container is null, then break. 364 | 365 |
Append container to fullscreenElements. 366 |
For each element in fullscreenElements: 372 | 373 |
Let doc be element's node document. 375 | 376 |
If element is doc's fullscreen element, continue. 378 | 379 |
No need to notify observers when nothing has changed. 380 | 381 |
If element is this and this is an <{iframe}> 382 | element, then set element's iframe fullscreen flag. 383 | 384 |
Fullscreen element within doc. 385 | 386 |
Append ({{fullscreenchange}}, element) to 387 | doc's list of pending fullscreen events. 388 |
The order in which elements are fullscreened 391 | is not observable, because run the fullscreen steps is invoked in tree order. 392 | 393 |
Resolve promise with undefined. 394 |
Implementations with out-of-process navigables are left as an exercise 397 | to the reader. Input welcome on potential improvements. 398 |
The fullscreenEnabled getter steps are to return
401 | true if this is allowed to use the "fullscreen" feature and fullscreen is supported, and
403 | false otherwise.
404 |
405 |
The fullscreen getter steps are to return false if
406 | this's fullscreen element is null, and true otherwise.
407 |
408 |
Use the {{DocumentOrShadowRoot/fullscreenElement}} attribute instead. 409 | 410 |
The
412 | fullscreenElement
413 | getter steps are:
414 |
415 |
If this is a shadow root and its host is not 417 | connected, then return null. 418 | 419 |
Let candidate be the result of retargeting fullscreen element 420 | against this. 421 | 422 |
If candidate and this are in the same tree, then return 423 | candidate. 424 | 425 |
Return null. 426 |
A document is said to be a simple fullscreen document if there is exactly one 430 | element in its top layer that has its fullscreen flag set. 431 | 432 |
A document with two elements in its top layer can be a 433 | simple fullscreen document. For example, in addition to the fullscreen element there 434 | could be an open <{dialog}> element. 435 | 436 |
To collect documents to unfullscreen given doc, run these steps: 438 | 439 |
Let docs be an ordered set consisting of doc. 441 | 442 |
While true: 444 | 445 |
Let lastDoc be docs's last document. 447 | 448 |
Assert: lastDoc's fullscreen element is not null. 449 | 450 |
If lastDoc is not a simple fullscreen document, break. 451 | 452 |
Let container be lastDoc's node navigable's 453 | container. 454 | 455 |
If container is null, then break. 456 | 457 |
If container's iframe fullscreen flag is set, break. 458 | 459 |
Append container's node document to docs. 460 |
Return docs. 463 | 464 |
This is the set of documents for which the fullscreen element will be 465 | unfullscreened, but the last document in docs might 466 | have more than one element in its top layer with the fullscreen flag set, 467 | in which case that document will still remain in fullscreen. 468 |
To exit fullscreen a document doc, run these steps: 473 | 474 |
Let promise be a new promise. 476 | 477 |
If doc is not fully active or doc's fullscreen element 478 | is null, then reject promise with a {{TypeError}} exception and return 479 | promise. 480 | 481 |
Let resize be false. 482 | 483 |
Let docs be the result of 484 | collecting documents to unfullscreen given 485 | doc. 486 | 487 | 488 |
Let topLevelDoc be doc's node navigable's 489 | top-level traversable's active document. 490 | 491 | 492 |
If topLevelDoc is in docs, and it is a 493 | simple fullscreen document, then set doc to topLevelDoc and 494 | resize to true. 495 | 496 |
If doc's fullscreen element is not connected: 497 |
Append ({{fullscreenchange}}, doc's 499 | fullscreen element) to doc's 500 | list of pending fullscreen events. 501 |
Return promise, and run the remaining steps in parallel. 504 | 505 |
Run the [=fully unlock the screen orientation steps=] with doc. 506 | 507 |
If resize is true, resize doc's viewport to its "normal" dimensions. 508 | 509 |
If doc's fullscreen element is null, then resolve promise with 510 | undefined and terminate these steps. 511 | 512 |
Let exitDocs be the result of 513 | collecting documents to unfullscreen given 514 | doc. 515 | 516 | 517 |
Let descendantDocs be an ordered set consisting of doc's 518 | descendant navigables' active documents whose 519 | fullscreen element is non-null, if any, in tree order. 520 | 521 | 522 |
For each exitDoc in exitDocs: 524 | 525 |
Append ({{fullscreenchange}}, exitDoc's 527 | fullscreen element) to exitDoc's list of pending fullscreen events. 528 | 529 |
If resize is true, unfullscreen 530 | exitDoc. 531 | 532 |
Otherwise, unfullscreen exitDoc's 533 | fullscreen element. 534 |
For each descendantDoc in descendantDocs: 538 | 539 |
Append ({{fullscreenchange}}, descendantDoc's 541 | fullscreen element) to descendantDoc's 542 | list of pending fullscreen events. 543 | 544 |
Unfullscreen descendantDoc. 545 |
The order in which documents are unfullscreened 548 | is not observable, because run the fullscreen steps is invoked in tree order. 549 | 550 |
Resolve promise with undefined. 551 |
The exitFullscreen() method steps are to return the
555 | result of running exit fullscreen on this.
556 |
557 |
The following are the event handlers (and their corresponding 560 | event handler event types) that must be supported by {{Element}} and {{Document}} objects as 561 | event handler IDL attributes: 562 | 563 |
| event handler 567 | | event handler event type 568 | |
|---|---|
onfullscreenchange
571 | | fullscreenchange
572 | |
onfullscreenerror
574 | | fullscreenerror
575 | |
These are not supported by {{ShadowRoot}} or {{Window}} objects, and there are no 578 | corresponding event handler content attributes for {{Element}} objects in any namespace. 579 | 580 | 581 | 582 |
User agents are encouraged to implement native media fullscreen controls in terms of 585 | {{Element/requestFullscreen()}} and {{Document/exitFullscreen()}}. 586 | 587 |
If the end user instructs the user agent to end a fullscreen session initiated via 588 | {{Element/requestFullscreen()}}, fully exit fullscreen given the 589 | top-level traversable's active document. 590 | 591 |
The user agent may end any fullscreen session without instruction from the end user 592 | or call to {{Document/exitFullscreen()}} whenever the user agent deems it necessary. 593 | 594 | 595 | 596 |
This section is to be interpreted equivalently to the Rendering section of HTML. [[!HTML]] 599 | 600 | 601 |
:fullscreen pseudo-classThe :fullscreen pseudo-class must match any
604 | element element for which one of the following conditions is true:
605 |
606 |
element's fullscreen flag is set. 608 | 609 |
element is a shadow host and the result of retargeting its 610 | node document's fullscreen element against element is element. 611 |
This makes it different from the 614 | {{DocumentOrShadowRoot/fullscreenElement}} API, which returns the topmost fullscreen element. 615 | 616 |
620 | @namespace "http://www.w3.org/1999/xhtml";
621 |
622 | *|*:not(:root):fullscreen {
623 | position:fixed !important;
624 | inset:0 !important;
625 | margin:0 !important;
626 | box-sizing:border-box !important;
627 | min-width:0 !important;
628 | max-width:none !important;
629 | min-height:0 !important;
630 | max-height:none !important;
631 | width:100% !important;
632 | height:100% !important;
633 | transform:none !important;
634 |
635 | /* intentionally not !important */
636 | object-fit:contain;
637 | }
638 |
639 | iframe:fullscreen {
640 | border:none !important;
641 | padding:0 !important;
642 | }
643 |
644 | *|*:not(:root):fullscreen::backdrop {
645 | background:black;
646 | }
647 |
648 |
649 |
650 |
651 | This specification defines a policy-controlled feature identified by the string
655 | "fullscreen". Its default allowlist is
656 | 'self'.
657 |
658 |
A document's permissions policy determines whether any content in that 660 | document is allowed to go fullscreen. If disabled in any document, no content in the document will 661 | be allowed to use fullscreen. 662 | 663 |
The <{iframe/allowfullscreen}> attribute of the HTML <{iframe}> element affects the container
664 | policy for any document nested in that iframe. Unless overridden by the <{iframe/allow}>
665 | attribute, setting <{iframe/allowfullscreen}> on an iframe is equivalent to <iframe
666 | allow="fullscreen *">, as described in
667 | [[permissions-policy#iframe-allowfullscreen-attribute]].
668 |
User agents should ensure, e.g. by means of an overlay, that the end user is aware something is 675 | displayed fullscreen. User agents should provide a means of exiting fullscreen that always works and 676 | advertise this to the user. This is to prevent a site from spoofing the end user by recreating the 677 | user agent or even operating system environment when fullscreen. See also the definition of 678 | {{Element/requestFullscreen()}}. 679 | 680 |
To enable content in a child navigable to go fullscreen, it needs to be specifically
681 | allowed via permissions policy, either through the <{iframe/allowfullscreen}> attribute of the HTML
682 | <{iframe}> element, or an appropriate declaration in the <{iframe/allow}> attribute of the HTML
683 | <{iframe}> element, or through a `Permissions-Policy` HTTP header
684 | delivered with the document through which it is nested.
685 |
686 |
This prevents e.g. content from third parties to go fullscreen without explicit permission. 687 | 688 | 689 | 690 |
Many thanks to Robert O'Callahan for designing the initial model and being awesome. 700 | 701 | 702 |
Thanks to 703 | Andy Earnshaw, 704 | Changwan Hong, 705 | Chris Pearce, 706 | Darin Fisher, 707 | Dave Tapuska, 708 | fantasai, 709 | Giuseppe Pascale, 710 | Glenn Maynard, 711 | Ian Clelland, 712 | Ian Hickson, 713 | Ignacio Solla, 714 | João Eiras, 715 | Josh Soref, 716 | Kagami Sascha Rosylight, 717 | Matt Falkenhagen, 718 | Mihai Balan, 719 | Mounir Lamouri, 720 | Øyvind Stenhaug, 721 | Pat Ladd, 722 | Rafał Chłodnicki, 723 | Riff Jiang, 724 | Rune Lillesveen, 725 | Sigbjørn Vik, 726 | Simon Pieters, 727 | Tab Atkins-Bittner, 728 | Takayoshi Kochi, 729 | Theresa O'Connor, 730 | triple-underscore, 731 | Vincent Scheib, and 732 | Xidorn Quan 733 | for also being awesome. 734 | 735 |
This standard is edited by Philip Jägenstedt 736 | (Google, 737 | philip@foolip.org). It was originally written by 738 | Anne van Kesteren 739 | (Apple, annevk@annevk.nl). 740 | Tantek Çelik 741 | (Mozilla, 742 | tantek@cs.stanford.edu) sorted out legal hassles. 743 | --------------------------------------------------------------------------------