Copyright © 2015 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.
The Screen Orientation API provides the ability to read the screen orientation type and angle, to be informed when the screen orientation state changes, and be able to lock the screen orientation to a specific state.
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 is still in a work in progress state. You can have a look at the opened issues. If you see any problem that is not in that list, feel free to discuss it in the mailing list or file an issue .
This document was published by the Web Applications Working Group as a 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). All comments are 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 document is governed by the 1 August 2014 W3C Process Document.
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.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to expose the APIs defined in this specification MUST implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [WEBIDL].
The following concepts and interfaces are defined in [HTML]:
Window
Document
Promise objects are defined in [ECMASCRIPT].
fullscreen element stack is defined in [FULLSCREEN].
now visible algorithm is defined in [PAGE-VISIBILITY].
Screen
interface
Screen
interface [CSSOM-VIEW], which this specification extends:
partial interface Screen {
readonly attribute ScreenOrientation
orientation;
};
The orientation
object is an instance of ScreenOrientation
, which is described
below.
ScreenOrientation
interface
interface ScreenOrientation : EventTarget {
Promise<void> lock (OrientationLockType
orientation);
void unlock ();
readonly attribute OrientationType
type;
readonly attribute unsigned short angle;
attribute EventHandler onchange;
};
When the
lock()
method is invoked, the user agent MUST run
the apply an orientation lock steps to the responsible
document using orientation.
When the unlock()
method is
invoked, the user agent MUST run the steps to lock the
orientation of the responsible document to the
responsible document's default orientation.
unlock() does not return a Promise because it is equivalent to locking to the default orientation which might or might not be known by the user agent. Hence, the user agent can not predict what the new orientation is going to be and even if it is going to change at all.
When getting the type
attribute, the
user agent MUST return the responsible document's
current orientation type.
When getting the angle
attribute, the
user agent MUST return the responsible document's
current orientation angle.
The onchange
attribute is
an event handler whose corresponding event handler event
type is change
.
OrientationType
enum
enum OrientationType {
"portrait-primary",
"portrait-secondary",
"landscape-primary",
"landscape-secondary"
};
OrientationLockType
enum
enum OrientationLockType {
"any",
"natural",
"landscape",
"portrait",
"portrait-primary",
"portrait-secondary",
"landscape-primary",
"landscape-secondary"
};
The term screen is equivalent to the screen of the output device associated to the Window, as per [CSSOM-VIEW].
Algorithms defined in this specification assume that for each
document there is a pending promise, which is
initially set to null
, which is a Promise object
whose associated operation is to lock the screen orientation.
When queuing a task, the screen orientation task source is used.
All documents have a current orientation type and a current orientation angle. Both of them SHOULD be initialized when the document is created, otherwise they MUST be initialized the first time they are accessed and before their value is read. The user agent MUST update the orientation information of the document to initialize them.
For a given document, the current orientation type and
the current orientation angle are strongly linked in the sense
that for any given type, there will be a specific angle associated.
However, the user agent can associate *-primary
and *-secondary
values at will. For example, if
90
is associated with landscape-primary
and
270
with landscape-secondary
for one
document , another one MAY get the opposite relationship.
Never assume any cross-devices relationship between the screen
orientation type and the screen orientation angle. Any assumption
would be wrong given that a device might have 90
and
270
as the angles for landscape
types but
another device will have 0
and 180
,
depending on its natural orientation. Instead, it is recommended to
check during runtime the relationship between angle and type.
The steps to update the orientation information of a document are as follows:
landscape-primary
or landscape-secondary
.
portrait-primary
or portrait-secondary
.
The decision whether the document's current orientation
type should be set to *-primary
or
*-secondary
is up to the user agent. For example,
it can be based on the device preferred angles, the user's preferred
orientations or the current orientation when the application starts.
However, a user agent MUST keep the screen orientation types
and the screen orientation angles relation consistent for any given
document.
The user agent MAY require a document and its associated browsing context to meet one or more security conditions in order to be able to lock the screen orientation. For example, a user agent might require a document's top-level browsing context to be fullscreen (see Interaction with FullScreen API) in order to allow an orientation lock.
The user agent MAY reject all attempts to lock the screen orientation if the platform conventions do not expect applications to be able to change the screen orientation. For example, on most desktop platforms, applications can not change the screen orientation.
If the user agent supports locking the screen orientation, it
MUST allow the screen to be locked to all of the states of the
OrientationLockType
enum.
A document's orientation lock is the orientation
lock that applies on its top-level browsing context. An
orientation lock is an unordered set of OrientationType
.
The steps to apply an orientation lock to a document using orientation are as follows:
DOMException
whose name is
NotSupportedError
and abort these steps.
null
:
null
pending promise.
DOMException
whose name is
AbortError
.
null
.
DOMException
whose name is SecurityError
and abort these steps.
portrait-primary
or portrait-secondary
or landscape-primary
or landscape-secondary
landscape
landscape-primary
, or
landscape-secondary
, or both to
orientations.
portrait
portrait-primary
, or
portrait-secondary
, or both to
orientations.
natural
portrait-primary
or
landscape-primary
to orientations such
as the associated screen orientation angle is 0.
any
portrait-primary
,
portrait-secondary
, landscape-primary
and landscape-secondary
to
orientations.
undefined
and set
pending-promise to null
.
When the user agent has to lock the orientation of a document to orientations, it MUST run the following steps:
To determine the active orientation lock, the user agent MUST run the following steps:
Whenever the active orientation lock changes, the user agent MUST run the steps to lock the orientation of the document to the document's orientation lock.
Whenever a top-level browsing context is navigated, the user agent MUST lock the orientation of the document to the document's default orientation.
Whenever the viewport is drawn at a different angle compared to the device's natural orientation, the user agent MUST asynchronously run the following steps:
null
:
undefined
.
null
.
change
at doc 's screen.orientation
object.
Whenever a document becomes visible per [PAGE-VISIBILITY], in other words after the now visible algorithm is run, the user agent MUST asynchronously run the following steps:
null
:
undefined
.
null
.
change
at the document's screen.orientation
object.
Developers need to be aware that a screen.orientation
object from a document that is not visible, as per
[PAGE-VISIBILITY], will not receive an orientation change event.
This is to prevent unnecessary changes to layout, etc. in the
non-visible web application.
A document's default orientation is the set of orientations to which the screen orientation is locked when it is not explicitly locked by this API or any other means.
For the perspective of a document, locking to the default
orientation is equivalent to unlocking because it means that it
no longer has a lock applied. However, it does not mean that the
default orientation has to be any
.
The [HTML] specification defines a sandboxing flag set which is extended with this value:
The algorithm to parse a sandboxing directive is also extended in step 3 such that:
allow-orientation-lock
keyword.
Finally, the
iframe's
sandbox attribute MUST add allow-orientation-lock
amongst its allowed values.
This section explains how this specification interacts with other related specifications of the platform.
As a security condition, a user agent MAY restrict locking the screen orientation exclusively to when the top-level browsing context's document's fullscreen element stack is not empty. When that security condition applies, whenever the document's fullscreen element stack is empty and a screen orientation lock is applied, the user agent MUST lock the orientation of the document to the document's default orientation.
This section is non-normative.
The DeviceOrientation specification [DEVICE-ORIENTATION] defines a
deviceorientation
event that can be used to discover the
physical orientation of the device. Such event can be used to draw
things on the screen that could point to a specific direction. A
basic example being a compass application. Another example would be
an application giving direction to the user or an augmented reality
game pointing to an objective.
Drawing on the screen in order to point to a physical location
requires to know the device orientation and the orientation of the
screen in the device coordinates. Without the APIs defined in this
specification, a developer has to assume that the document's
current orientation angle is 0
. With the help of
the APIs described in this specification, the developer can apply
an orientation lock to a document using
natural
to make that assumption a certitude. Otherwise,
reading the document's current orientation angle via
screen.orientation.angle
and listening to the
change
event can help the developer to compensate the
screen orientation angle.
This section is non-normative.
The Web Application Manifest specification [appmanifest] allows web applications to set the document's default orientation.
This section is non-normative.
The CSS Device Adaptation specification [CSS-ADAPTATION] defines, independently of this document, a way to lock the screen orientation for a web page using CSS.
This section is non-normative.
This example shows the current screen orientation to the console every time the screen orientation state changes.
<script> var show = function() { console.log("Orientation type is " + screen.orientation.type); console.log("Orientation angle is " + screen.orientation.angle); } screen.orientation.addEventListener("change", show); window.onload = show; </script> <button onclick='screen.orientation.unlock()'> Unlock </button> <button onclick="screen.orientation.lock('portrait')"> Lock to portrait </button> <button onclick="screen.orientation.lock('landscape')"> Lock to landscape </button>
This example waits to be fullscreen before locking the screen orientation and starting.
<script> var start = function() { document.onfullscreenchange = function() { screen.orientation.lock('natural').then(startInternal); } document.documentElement.requestFullscreen(); } </script> <button onclick='start();'> Start </button>
This example asks the user to manually rotate the device if the Screen Orientation API is not available.
<script> var start = function() { screen.orientation.lock('landscape-primary').then( startInternal, function() { alert('To start, rotate your screen to landscape.'); var orientationChangeHandler = function() { if (!screen.orientation.type.startsWith('landscape')) { return; } screen.orientation.removeEventListener('change', orientationChangeHandler); startInternal(); } screen.orientation.addEventListener('change', orientationChangeHandler); }); } window.onload = start; </script>
Thanks to Marcos Cáceres, Christophe Dumez, Anne van Kesteren and Chundong Wang for their useful comments.
Special thanks to Chris Jones and Jonas Sicking for their contributions to the initial design of this API.