69 | This demo shows how to use the 70 | Screen Orientation Lock API 73 | to lock the screen orientation to portrait or landscape. 74 |
75 |Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
477 | The Screen Orientation API's goal is to provide an interface for web applications 478 | to be able to read the screen orientation state, to be informed when this state 479 | changes and to be able to lock the screen orientation to a specific state. 480 |
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document was published by the Web Applications Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives) with [screen-orient] at the start of the subject header. All feedback is welcome.
Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
484 |485 | The Screen Orientation API provides an interface for web applications to 486 | access and lock the user's device's screen orientation state. 487 |
488 |489 | This examples is an application that shows the current screen orientation 490 | to the user every time the screen orientation state changes: 491 |
492 |<!DOCTYPE html>
493 | <html>
494 | <script>
495 | function show() {
496 | alert("Screen orientation state is " + screen.orientation);
497 | }
498 |
499 | screen.addEventListener("orientationchange", show, false);
500 |
501 | show();
502 | </script>
503 | </html>
504 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
507 |The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].
508 | 509 |510 | This specification defines conformance criteria that apply to a single product: the user agent that 511 | implements the interfaces that it contains. 512 |
513 |514 | Implementations that use ECMAScript to expose the APIs defined in this specification must implement them in a manner 515 | consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. 516 |
517 |
523 | The
524 | Function interface represents a function in the scripting
525 | language being used as defined in [HTML5].
526 |
528 | The concepts 529 | queue a task and 530 | 531 | fire a simple event are defined in [HTML5]. 532 |
533 |534 | The terms 535 | event handlers and 536 | 537 | event handler event types are defined in [HTML5]. 538 |
539 |540 | The concepts of 541 | browsing context and 542 | 543 | active document are defined in [HTML5]. 544 |
545 | 546 |550 | The current orientation should be an orientation amongst those values: 551 |
portrait-primary, if the orientation is in the primary portrait mode;portrait-secondary, if the orientation is in the secondary portrait mode;landscape-primary, if the orientation is in the primary landscape mode;landscape-secondary, if the orientation is in the secondary landscape mode.
561 | The notion of primary and secondary depends on the device and the platform. Usually, platforms have a way to distinguish
562 | the two portrait and landscape orientations.
563 | For example, on most phones, portrait-primary is going to be the orientation that is used when the phone
564 | is in hand and secondary will be upside-down orientation. Also, landscape-primary will be the landscape orientation
565 | that is a 90 degree orientation counter-clock and secondary the other one.
566 | On tablets, landscape-primary will be the orientation used when the tablet is in hands.
567 |
575 | The allowed orientations should be orientations amongst the current orientation list 576 | or amongst those values: 577 |
portrait, value that covers portrait-primary and portrait-secondary cases;
579 | landscape, value that covers landscape-primary and landscape-secondary cases;
580 | Screen InterfaceScreen interface [CSSOM-VIEW], which this specification extends:
588 | partial interface Screen {
589 | readonly attribute DOMString orientation;
590 | boolean lockOrientation (DOMtring orientation);
591 | void unlockOrientation ();
592 | [TreatNonCallableAsNull]
593 | attribute Function? onorientationchange;
594 | };
595 | onorientationchange of type Function, nullableorientation of type DOMString, readonly597 | The user agent must return the value of the orientation of the output device. 598 |
599 |600 | The returned orientation must be in the current orientation list. 601 |
602 |lockOrientationorientationnchange at the Screen object.
611 | | Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| orientation | DOMtring | ✘ | ✘ |
booleanunlockOrientation
613 | The user agent must disable the current lock applied on the screen with lockOrientation.
614 | If the current browsing context has a default orientation, the screen orientation should revert to that.
615 |
void
619 | When the screen orientation changes in the current browsing context, the user agent must queue a task
620 | which updates the orientation attribute and fire a simple event named orientationchange
621 | at the Screen object.
622 |
623 |
625 | For example, that means if an application A is locked to landscape-primary
626 | and application B is locked to portrait-primary, switching from
627 | application A to B or B to A will not fire an orientationchange
628 | event because both application will keep the orientation they had.
629 |
631 | However, locking the application can fire an orientationchange if the
632 | application wasn't in the specified type before being locked.
633 |
641 | The following are the event handlers (and their corresponding
642 | event handler event types) that must be supported as attributes
643 | by the Screen object:
644 |
| event handler | 650 |event handler event type | 651 |
|---|---|
onorientationchange |
656 | orientationchange |
657 |
No informative references.
410 |
411 |
412 |
413 |
447 | Copyright © 448 | 2012 449 | 450 | W3C® 451 | (MIT, 452 | ERCIM, 453 | Keio), All Rights Reserved. 454 | W3C liability, 455 | trademark and 456 | document use rules apply. 457 |
458 | 459 | 460 |464 | The Screen Orientation API's goal is to provide an interface for web applications 465 | to be able to read the screen orientation state, to be informed when this state 466 | changes and to be able to lock the screen orientation to a specific state. 467 |
472 | This section describes the status of this document at the time of its publication. Other 473 | documents may supersede this document. A list of current W3C publications and the latest revision 474 | of this technical report can be found in the W3C technical reports 475 | index at http://www.w3.org/TR/. 476 |
477 | 478 |
479 | This document was published by the Web Applications Working Group as a Working Draft.
480 |
481 | This document is intended to become a W3C Recommendation.
482 |
483 | If you wish to make comments regarding this document, please send them to
484 | public-webapps@w3.org
485 | (subscribe,
486 | archives) with [screen-orient] at the start of the subject header.
487 |
488 | A bug list for this document is available.
489 |
490 | All feedback is welcome.
491 |
494 | Publication as a Working Draft does not imply endorsement by the W3C Membership. 495 | This is a draft document and may be updated, replaced or obsoleted by other documents at 496 | any time. It is inappropriate to cite this document as other than work in progress. 497 |
498 | 499 | 500 |501 | 502 | This document was produced by a group operating under the 503 | 5 February 2004 W3C Patent Policy. 504 | 505 | 506 | 507 | 508 | W3C maintains a public list of any patent disclosures 509 | 510 | made in connection with the deliverables of the group; that page also includes instructions for 511 | disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains 512 | Essential Claim(s) must disclose the 513 | information in accordance with section 514 | 6 of the W3C Patent Policy. 515 | 516 | 517 |
518 | 519 | 520 | 521 | 522 |This section is non-normative.
526 |527 | The Screen Orientation API provides an interface for web applications to 528 | access and lock the user's device's screen orientation state. 529 |
530 |531 | This examples is an application that shows the current screen orientation 532 | to the user every time the screen orientation state changes: 533 |
534 |<!DOCTYPE html> 535 | <html> 536 | <script> 537 | function show() { 538 | alert("Screen orientation state is " + screen.orientation); 539 | } 540 | 541 | screen.addEventListener("orientationchange", show, false); 542 | 543 | show(); 544 | </script> 545 | </html>
550 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, 551 | and notes in this specification are non-normative. Everything else in this specification is 552 | normative. 553 |
554 |555 | The key words must, must not, required, should, should not, recommended, may, 556 | and optional in this specification are to be interpreted as described in [RFC2119]. 557 |
558 | 559 |560 | This specification defines conformance criteria that apply to a single product: the user agent that 561 | implements the interfaces that it contains. 562 |
563 |564 | Implementations that use ECMAScript to expose the APIs defined in this specification must implement them in a manner 565 | consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. 566 |
567 |573 | The 574 | EventHandler interface represents a callback used for event 575 | handlers as defined in [HTML5]. 576 |
577 |578 | The concepts 579 | queue a task and 580 | 581 | fire a simple event are defined in [HTML5]. 582 |
583 |584 | The terms 585 | event handlers and 586 | 587 | event handler event types are defined in [HTML5]. 588 |
589 |590 | The concepts of 591 | browsing context and 592 | 593 | active document are defined in [HTML5]. 594 |
595 | 596 |600 | The current orientation should be an orientation amongst those values: 601 |
portrait-primary, if the orientation is in the primary portrait mode;portrait-secondary, if the orientation is in the secondary portrait mode;landscape-primary, if the orientation is in the primary landscape mode;landscape-secondary, if the orientation is in the secondary landscape mode.
610 | The notion of primary and secondary depends on the device and the
611 | platform. Some devices are in portrait mode when the user holds the
612 | device in the normal orientation, other devices are in landscape
613 | mode when the user holds the device in its normal orientation. For
614 | devices whose normal orientation is a landscape mode, that normal
615 | orientation should be represented as landscape-primary.
616 | For devices whose normal orientation is a portrait mode, that normal
617 | orientation should be represented as portrait-primary.
618 | In both if the device is in landscape-primary and is
619 | rotated 90 degrees clockwise, that should be represented as
620 | portrait-primary.
621 |
629 | The allowed orientations should be orientations amongst those values: 630 |
portrait-primary, if the orientation is in the primary portrait mode;portrait-secondary, if the orientation is in the secondary portrait mode;landscape-primary, if the orientation is in the primary landscape mode;landscape-secondary, if the orientation is in the secondary landscape mode.portrait, value that represents portrait-primary and portrait-secondary cases;
636 | landscape, value that represents landscape-primary and landscape-secondary cases;
637 |
645 | The action to lock the orientation consists of forcing the rendering of the current browsing context
646 | to be shown as if the screen was oriented in one or many of the current orientation.
647 | If the lock is done on only one orientation, the screen orientation should stay on the given orientation and never change
648 | until the screen orientation is unlocked. Otherwise, the screen orientation should be able to change from an orientation
649 | to another as long as the orientations are amongst an orientation it has been locked to.
650 |
657 | A set of orientations is said to be a supported orientation set if the user agent 658 | can lock the orientation to that set. 659 |
660 |Screen InterfaceScreen interface [CSSOM-VIEW], which this specification extends:
667 | partial interface Screen {
668 | readonly attribute DOMString orientation;
669 | boolean lockOrientation (DOMString orientation);
670 | boolean lockOrientation (sequence<DOMString> orientations);
671 | void unlockOrientation ();
672 | [TreatNonCallableAsNull]
673 | attribute EventHandler onorientationchange;
674 | };onorientationchange of type EventHandler, nullableorientation of type DOMString, readonly676 | The user agent must return the value representing the orientation of the screen. 677 |
678 |679 | The returned orientation must be in the current orientation list. 680 |
681 |lockOrientation| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| orientation | DOMString | ✘ | ✘ |
booleanlockOrientation| Parameter | Type | Nullable | Optional | Description |
|---|---|---|---|---|
| orientations | sequence<DOMString> | ✘ | ✘ |
booleanunlockOrientation
691 | The user agent must disable the current lock applied on the screen with lockOrientation.
692 | If the current browsing context has a default orientation, the screen orientation should revert to that.
693 | Otherwise, the screen orientation should revert to any value the user agent believes appropriate.
694 |
696 | When the unlock is done, if the orientation actually changed, the user agent must fire a simple event
697 | named orientationnchange at the Screen object.
698 |
void
702 | When the screen orientation changes in the current browsing context, the user agent must queue a task
703 | which updates the orientation attribute and fire a simple event named orientationchange
704 | at the Screen object.
705 |
706 |
708 | For example, that means if an application A is locked to landscape-primary
709 | and application B is locked to portrait-primary, switching from
710 | application A to B or B to A will not fire an orientationchange
711 | event because both applications will keep the orientation they had.
712 |
714 | However, locking the orientation can fire an orientationchange if the
715 | orientation had to be changed to satisfy the lock requirements.
716 |
722 | The steps for locking the screen orientation are the following: 723 |
orientationnchange at the Screen object.This section is non-normative.
744 |745 | This specification doesn't intend to specify a declarative orientation locking. However, other specifications specify ways to do that. 746 |
747 |
748 | The Web Application Manifest Format and Management APIs [WEBAPPS-MANIFEST-API] specifies a way to declare a default orientation
749 | for a web application inside the manifest file.
750 | That specification tries to follow this specification regarding orientation keywords.
751 |
753 | The CSS Device Adaptation specification [CSS-ADAPTATION] specifies a way to declare a default orientation for a web page.
754 | That specification isn't yet in sync with this specification.
755 |
761 | The following are the event handlers (and their corresponding
762 | event handler event types) that must be supported as attributes
763 | by the Screen object:
764 |
| event handler | 770 |event handler event type | 771 |
|---|---|
onorientationchange |
776 | orientationchange |
777 |
44 | The Screen Orientation specification standardizes the 45 | types and angles for a device's screen orientation, and provides a 46 | means for locking and unlocking it. The API, defined by this 47 | specification, exposes the current type and angle of the device's 48 | screen orientation, and dispatches events when it changes. This enables 49 | web applications to programmatically adapt the user experience for 50 | multiple screen orientations, working alongside CSS. This API is 51 | particularly useful for applications such as computer games, where 52 | users physically rotate the device, but the screen orientation itself 53 | should not change. The API restricts locking the screen orientation 54 | only if certain [=pre-lock conditions=] are met. 55 |
56 |59 | This document is a work in progress. 60 |
61 |67 | In this example, selecting the "Lock" button requests to go into 68 | fullscreen and then locks the screen to the opposite orientation. 69 | Selecting the "Unlock" button unlocks the screen. 70 |
71 |
73 | <script>
74 | function updateLockButton() {
75 | const lockButton = document.getElementById("button");
76 | const newOrientation = getOppositeOrientation();
77 | lockButton.textContent = `Lock to ${newOrientation}`;
78 | }
79 |
80 | function getOppositeOrientation() {
81 | return screen
82 | .orientation
83 | .type
84 | .startsWith("portrait") ? "landscape" : "portrait";
85 | }
86 |
87 | async function rotate(lockButton) {
88 | if (!document.fullscreenElement) {
89 | await document.documentElement.requestFullscreen();
90 | }
91 | const newOrientation = getOppositeOrientation();
92 | await screen.orientation.lock(newOrientation);
93 | updateLockButton(lockButton);
94 | }
95 |
96 | screen.orientation.addEventListener("change", updateLockButton);
97 |
98 | window.addEventListener("load", updateLockButton);
99 | </script>
100 |
101 | <button onclick="rotate(this)" id="button">
102 | Lock to...
103 | </button>
104 | <button onclick="screen.orientation.unlock()">
105 | Unlock
106 | </button>
107 |
108 | 114 | To lock the 115 | screen orientation to an {{OrientationLockType}} |orientation| 116 | means that the screen can only be rotated by the user to a specific 117 | [=screen orientation=] - possibly at the exclusion of other 118 | orientations. The possible orientations to which the screen can be 119 | rotated is determined by the user agent, a user preference, the 120 | operating system's conventions, or the screen itself. For example, 121 | locking the orientation to [=landscape=] means that the screen can be 122 | rotated by the user to [=landscape-primary=] and maybe 123 | [=landscape-secondary=] if the system allows it, but won't change the 124 | orientation to [=portrait-secondary=] orientation. 125 |
126 |127 | To unlock the screen 129 | orientation the end user is unrestricted to rotate the screen to 130 | any [=screen orientation=] that the system allows. 131 |
132 |137 | A screen can be in, or [=locked=] to, one of the following 138 | screen orientations: 139 |
140 |209 | The screen of the output device has the following associated 210 | concepts: 211 |
212 |238 | The screen orientation values lists below standardize the 239 | angles associated with each screen orientation type for screens with 240 | different [=natural=] orientations: 241 |
242 |285 | The {{Document}} interface is extended with the following internal 286 | slots: 287 |
288 || 292 | Internal Slot 293 | | 294 |295 | Description 296 | | 297 |
|---|---|
| 302 | [[\orientationPendingPromise]] 304 | | 305 |306 | Either `null` or a {{Promise}}. When assigned a {{Promise}}, 307 | that promise represents a request to lock the screen 308 | orientation. 309 | | 310 |
320 | partial interface Screen {
321 | [SameObject] readonly attribute ScreenOrientation orientation;
322 | };
323 |
324 | 325 | The {{Window}} object has an associated `ScreenOrientation`, 326 | which is a {{Screen}}'s {{Screen/orientation}} object (i.e., the 327 | {{ScreenOrientation}} instance at `window.screen.orientation`). 328 |
329 |
336 | [Exposed=Window]
337 | interface ScreenOrientation : EventTarget {
338 | Promise<undefined> lock(OrientationLockType orientation);
339 | undefined unlock();
340 | readonly attribute OrientationType type;
341 | readonly attribute unsigned short angle;
342 | attribute EventHandler onchange;
343 | };
344 |
345 | | 353 | Internal Slot 354 | | 355 |356 | Description 357 | | 358 |
|---|---|
| 363 | [[\angle]] 364 | | 365 |366 | Represents the screen's last known [=Screen/current orientation 367 | angle=] in degrees as an {{unsigned short}} as derived from the 368 | [=screen orientation values lists=]. 369 | | 370 |
| 373 | [[\initialType]] 374 | | 375 |376 | Represents the screen's [=Screen/current orientation type=] 377 | when the [=browsing context=] was created. 378 | | 379 |
| 382 | [[\type]] 383 | | 384 |385 | Represents the screen's last known [=Screen/current orientation 386 | type=] as an {{OrientationType}} enum value. 387 | | 388 |
397 | pre-lock conditions are optional requirements that a 398 | [=user agent=] MAY impose before allowing screen orientation locking. 399 | Common pre-lock conditions include requiring the document to be in 400 | fullscreen mode or being part of an installed web application. See 401 | [[[#appmanifest-interaction]]] and [[[#fullscreen-interaction]]] for 402 | specific examples. 403 |
404 |405 | When the {{lock()}} method is invoked with {{OrientationLockType}} 406 | |orientation:OrientationLockType|, the [=user agent=] MUST run the 407 | following steps. 408 |
409 |446 | When the {{unlock()}} method is invoked, the [=user agent=] MUST run 447 | the following steps: 448 |
449 |468 | {{unlock()}} does not return a promise because it is equivalent to 469 | locking to the [=default screen orientation=] which might or might 470 | not be known by the [=user agent=]. Hence, the [=user agent=] can not 471 | predict what the new orientation is going to be and even if it is 472 | going to change at all. 473 |
474 |480 | The common safety checks for a {{Document}} 481 | |document:Document| are the following steps: 482 |
483 |504 | When getting, the {{type}} attribute returns [=this=]'s 505 | {{ScreenOrientation/[[type]]}}. 506 |
507 |513 | When getting, the {{angle}} attribute returns [=this=]'s 514 | {{ScreenOrientation/[[angle]]}}. 515 |
516 | 525 |532 | The {{onchange}} attribute is an [=event handler IDL attribute=] for 533 | the {{onchange}} [=event handler=], whose [=event handler event type=] 534 | is change. 535 |
536 |
542 | enum OrientationLockType {
543 | "any",
544 | "natural",
545 | "landscape",
546 | "portrait",
547 | "portrait-primary",
548 | "portrait-secondary",
549 | "landscape-primary",
550 | "landscape-secondary"
551 | };
552 |
553 | 554 | The {{OrientationLockType}} enum represents the screen orientations to 555 | which a screen can be potentially [=locked=]. 556 |
557 | 565 |
590 | enum OrientationType {
591 | "portrait-primary",
592 | "portrait-secondary",
593 | "landscape-primary",
594 | "landscape-secondary"
595 | };
596 |
597 | 598 | The {{OrientationType}} enum values are used to represent the screen's 599 | [=Screen/current orientation type=]. 600 |
601 |622 | When a [=browsing context=] |context| is created, the [=user agent=] 623 | MUST: 624 |
625 |646 | When steps require to reject and nullify the current lock 647 | promise of {{Document}} |document| with a {{DOMString}} 648 | |exceptionName|, the [=user agent=] MUST: 649 |
650 |670 | When steps require to apply orientation lock of 671 | {{OrientationLockType?}} |orientation| to {{Document}} |document|, the 672 | [=user agent=] MUST perform the following steps: 673 |
674 |732 | This can happen if the user has set a preference that prevents 733 | web applications from changing the screen orientation, or if 734 | the underlying platform, rather than the user agent, does not 735 | allow locking the screen orientation to the given 736 | |orientation|. Note that differences in user preferences or 737 | platform capabilities could potentially be used for 738 | fingerprinting, as they may create detectable patterns in lock 739 | failure behavior. 740 |
741 |778 | When a user-agent determines that the screen's orientation has changed 779 | for a [=top-level traversable=], or the user moves the [=top-level 780 | browsing context=] to a different screen, then run the [=screen 781 | orientation change steps=] with the [=top-level traversable=]'s 782 | [=navigable/active document=]. 783 |
784 |785 | The screen orientation change steps for 786 | {{Document}} |document:Document| are as follows: 787 |
788 |830 | [[HTML]]'s "update the visibility state" algorithm runs the [=screen 831 | orientation change steps=]. 832 |
833 | 842 |846 | Whenever the [=unloading document cleanup steps=] run with a 847 | |document|, the user agent MUST run the following steps: 848 |
849 |861 | The fully unlock the screen orientation steps 862 | for {{Document}} |document:Document| are as follows: 863 |
864 |881 | A user agent MUST restrict the use of {{ScreenOrientation/lock()}} to 882 | simple fullscreen documents as a [=pre-lock condition=]. This 883 | requirement prevents fingerprinting through differences in user agent 884 | behavior regarding orientation locking permissions. [[fullscreen]] 885 |
886 |887 | When a [=document=] exits fullscreen, it also runs the [=fully unlock 888 | the screen orientation steps=]. [[fullscreen]] 889 |
890 |896 | The [[[appmanifest]]] specification allows web applications to set the 897 | [=default screen orientation=] via the the [=manifest/orientation=] 898 | member. 899 |
900 |901 | A user agent SHOULD require [=installed web applications=] to be 902 | presented in the "fullscreen" [=display mode=] as a [=pre-lock 903 | condition=]. 904 |
905 |911 | As users can have their devices mounted in a fixed orientation (e.g. on 912 | the arm of a wheelchair), developers that expect users to rotate their 913 | device when [=locking the screen orientation=] need to be aware of the 914 | [[[WCAG21]]]'s Orientation Success 915 | Criterion. The criterion makes it essential that content and functionality is 917 | available regardless of the [=screen orientation=]. When a particular 918 | orientation is essential, web 919 | applications must advise the user of the orientation requirements. 920 |
921 |927 | A screen's [=Screen/current orientation type|type=] and 928 | [=Screen/current orientation angle|angle=] are a potential 929 | fingerprinting vectors. The following mitigations help protect a user's 930 | privacy by not revealing how a device is being held, and also prevent 931 | the [=secondary=] orientation type and associated angles from being 932 | used for fingerprinting purposes. 933 |
934 |938 | To protect user privacy, orientation change events are subject to 939 | several delivery restrictions: 940 |
941 |953 | The requirement for [=documents=] to be [=Document/fully active 954 | descendant of a top-level traversable with user attention=] ensures 955 | that orientation events are only delivered to documents in windows that 956 | are both visible at the system level and have the user's attention 957 | (either through focus or the ability to receive keyboard input). The 958 | additional visibility state check provides defense in depth. These 959 | restrictions prevent background tabs, hidden windows, and minimized 960 | applications from collecting orientation data for fingerprinting 961 | purposes. 962 |
963 |967 | To resist fingerprinting, user agents SHOULD implement the following 968 | protections, particularly in privacy-conscious contexts such as private 969 | browsing modes: 970 |
971 |1001 | Thanks Christophe Dumez, Anne van Kesteren, Chundong Wang, Fuqiao Xue, 1002 | and Chaals McCathie Nevile for their useful comments. 1003 |
1004 |1005 | Special thanks to Chris Jones and Jonas Sicking for their contributions 1006 | to the initial design of this API. 1007 |
1008 |
435 |
436 |
437 |
438 |
475 | Copyright © 476 | 2014 477 | 478 | W3C® 479 | (MIT, 480 | ERCIM, 481 | Keio, Beihang), 482 | 483 | All Rights Reserved. 484 | 485 | W3C liability, 486 | trademark and 487 | 488 | document use 489 | 490 | rules apply. 491 |
492 | 493 | 494 |497 | The Screen Orientation API provides the ability to read the 498 | screen orientation state, to be informed when this state changes, and to 499 | be able to lock the screen orientation to a specific state. 500 |
505 | This section describes the status of this document at the time of its publication. 506 | Other documents may supersede this document. A list of current W3C publications and the 507 | latest revision of this technical report can be found in the W3C technical reports index at 508 | http://www.w3.org/TR/. 509 |
510 | 511 | This document is still in a work in progress state. You can have a look at 512 | the 513 | opened bugs. If you see any problem that is not in that list, feel 514 | free to discuss it in the mailing list (see below) or 515 | open a new bug. 516 | 517 |518 | This document was published by the Web Applications Working Group as a Working Draft. 519 | 520 | This document is intended to become a W3C Recommendation. 521 | 522 | 523 | If you wish to make comments regarding this document, please send them to 524 | public-webapps@w3.org 525 | (subscribe, 526 | archives). 527 | 528 | 529 | 530 | 531 | All comments are welcome. 532 | 533 |
534 | 535 | 536 |537 | Publication as a Working Draft does not imply endorsement by the W3C 538 | Membership. This is a draft document and may be updated, replaced or obsoleted by other 539 | documents at any time. It is inappropriate to cite this document as other than work in 540 | progress. 541 |
542 | 543 | 544 | 545 |546 | 547 | This document was produced by a group operating under the 548 | 5 February 2004 W3C Patent 549 | Policy. 550 | 551 | 552 | 553 | 554 | W3C maintains a public list of any patent 555 | disclosures 556 | 557 | made in connection with the deliverables of the group; that page also includes 558 | instructions for disclosing a patent. An individual who has actual knowledge of a patent 559 | which the individual believes contains 560 | Essential 561 | Claim(s) must disclose the information in accordance with 562 | section 563 | 6 of the W3C Patent Policy. 564 | 565 | 566 |
567 | 568 | 569 | 570 | 571 |This section is non-normative.
601 |602 | The Screen Orientation API provides an interface for web applications 603 | to access and lock the device's screen orientation state. 604 |
605 |606 | This examples is an application that shows the current screen 607 | orientation to the user every time the screen orientation state 608 | changes: 609 |
610 |<!DOCTYPE html> 611 | <html> 612 | <head> 613 | <title>Screen Orientation API Example 1</title> 614 | <script> 615 | function show() { 616 | alert("Screen orientation state is now " + screen.orientation); 617 | } 618 | 619 | screen.addEventListener("orientationchange", show); 620 | window.addEventListener("load", show); 621 | </script> 622 | </head> 623 | <body> 624 | <input type='button' value='Unlock' 625 | onclick='screen.unlockOrientation();'> 626 | <input type='button' value='Lock to portrait' 627 | onclick="screen.lockOrientation('portrait');"> 628 | <input type='button' value='Lock to landscape' 629 | onclick="screen.lockOrientation('landscape');"> 630 | </body> 631 | </html>
635 | As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, 636 | and notes in this specification are non-normative. Everything else in this specification is 637 | normative. 638 |
639 |640 | The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, 641 | and OPTIONAL in this specification are to be interpreted as described in [RFC2119]. 642 |
643 | 644 |645 | This specification defines conformance criteria that apply to a single 646 | product: the user agent that implements the interfaces that 647 | it contains. 648 |
649 |650 | Implementations that use ECMAScript to expose the APIs defined in this 651 | specification MUST implement them in a manner consistent with the 652 | ECMAScript Bindings defined in the Web IDL specification [WEBIDL]. 653 |
654 |660 | The EventHandler 661 | interface represents a callback used for event handlers as defined in 662 | [HTML5]. 663 |
664 |
665 | The concepts queue a
666 | task and fire
667 | a simple event are defined in [HTML5].
668 | Unless specified otherwise, when queuing a task, the screen
669 | orientation task source is used.
670 |
672 | The terms event 673 | handlers and 674 | event handler event types are defined in [HTML5]. 675 |
676 |677 | The concepts of browsing 678 | context and active 679 | document are defined in [HTML5]. 680 |
681 |686 | The current orientation is represented by one of the 687 | following values: 688 |
689 |portrait-primary
692 | portrait-secondary
698 | landscape-primary
704 | landscape-secondary
710 |
716 | The concepts of primary orientation and secondary orientation depends
717 | on the device and the platform. Some devices are in portrait mode when
718 | the user holds the device in the normal orientation, other devices are
719 | in landscape mode when the user holds the device in its normal
720 | orientation. For devices whose normal orientation is a landscape mode,
721 | that normal orientation SHOULD be represented as
722 | landscape-primary. For devices whose normal orientation
723 | is a portrait mode, that normal orientation SHOULD be represented as
724 | portrait-primary. In both if the device is in
725 | landscape-primary and is rotated 90 degrees clockwise,
726 | that SHOULD be represented as portrait-primary.
727 |
734 | The allowed orientations are represented by the following 735 | values: 736 |
737 |portrait-primary
740 | portrait-secondary
746 | landscape-primary
752 | landscape-secondary
758 | portrait
764 | portrait-primary or
767 | portrait-secondary.
768 | landscape
771 | landscape-primary or
774 | landscape-secondary.
775 | 785 | To lock the orientation means forcing the rendering of the 786 | current browsing context to behave as if the screen was 787 | naturally orientated in a given orientation and will only change 788 | orientation to a given set of allowed orientations, regardless 789 | of the actual screen orientation relative to the user or the previous 790 | locks. 791 |
792 |793 | If the lock is done on only one orientation, the screen orientation 794 | MUST stay on the given orientation and never change until the 795 | screen orientation is locked again. Otherwise, the screen orientation 796 | MUST be able to change from an orientation to another as long as 797 | the orientations are amongst an orientation it has been locked to. 798 |
799 |
800 | When the lock is done, if the orientation actually changed, the
801 | user agent MUST fire a simple event named
802 | orientationnchange at the Screen object.
803 |
810 | The supported orientations is a set of orientations that a 811 | user agent can lock the orientation to. 812 |
813 |819 | The browsing context's default orientation is the 820 | set of orientations to which the screen orientation would be locked 821 | when it is not explicitly locked by the current browsing 822 | context. 823 |
824 |Screen Interface
829 | Screen interface
830 | [CSSOM-VIEW], which this specification extends:
831 | partial interface Screen : EventTarget {
832 | readonly attribute DOMString orientation;
833 | boolean lockOrientation ((DOMString or sequence<DOMString>) orientations);
834 | void unlockOrientation ();
835 | attribute EventHandler onorientationchange;
836 | };
837 |
838 | The orientation attribute MUST return the value
839 | representing the orientation of the screen. The returned orientation
840 | MUST be in the current orientation list.
841 |
843 | The lockOrientation() method, when invoked, MUST run the
844 | steps for locking the screen orientation. If
845 | lockOrientation was called with a sequence of strings, the
846 | sequence MUST be used as orientation in the mentioned steps.
847 | Otherwise, the passed string MUST be the only element in
848 | orientations. The method MUST return the result returned from
849 | running previous steps.
850 |
852 | The unlockOrientation() method, when invoked, MUST
853 | asynchronously lock the orientation to the default
854 | orientation. The user agent MAY ignore this call if the
855 | screen is already locked to the default orientation.
856 |
858 | When the screen orientation changes in the current browsing
859 | context, the user agent MUST queue a task which
860 | updates the orientation attribute and fire a simple
861 | event named orientationchange at the
862 | Screen object.
863 |
866 | For example, that means if an application A is locked to
867 | landscape-primary and application B is locked to
868 | portrait-primary, switching from application A to B or B
869 | to A will not fire an orientationchange event because
870 | both applications will keep the orientation they had.
871 |
873 | However, locking the orientation can fire an
874 | orientationchange if the orientation had to be changed
875 | to satisfy the lock requirements.
876 |
883 | The steps for locking the screen orientation are as 884 | follows: 885 |
886 |This section is non-normative.
922 |923 | This specification doesn't intend to specify a declarative orientation 924 | locking. However, other specifications specify ways to do that. 925 |
926 |927 | The Web Application Manifest Format and Management APIs 928 | [WEBAPPS-MANIFEST-API] specifies a way to declare a default 929 | orientation for a web application inside the manifest file. That 930 | specification tries to follow this specification regarding orientation 931 | keywords. 932 |
933 |934 | The CSS Device Adaptation specification [CSS-ADAPTATION] specifies a 935 | way to declare a default orientation for a web page. That specification 936 | isn't yet in sync with this specification. 937 |
938 |
944 | The following are the event handlers (and their corresponding
945 | event handler event types) that MUST be supported as attributes
946 | by the Screen object:
947 |
| 952 | event handler 953 | | 954 |955 | event handler event type 956 | | 957 |
|---|---|
962 | onorientationchange
963 | |
964 |
965 | orientationchange
966 | |
967 |
976 | Thanks to Marcos Cáceres, Christophe Dumez, Anne van Kesteren and 977 | Chundong Wang for their useful comments. 978 |
979 |980 | Special thanks to Chris Jones and Jonas Sicking for their contributions 981 | to the initial design of this API. 982 |
983 |