Abstract

The Screen Orientation API provides the ability to read the screen orientation state, to be informed when this state changes, and to be able to lock the screen orientation to a specific state.

Status of This Document

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 bugs. If you see any problem that is not in that list, feel free to discuss it in the mailing list (see below) or open a new bug.

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.

Table of Contents

1. Introduction

This section is non-normative.

The Screen Orientation API provides an interface for web applications to access and lock the device's screen orientation state.

This examples is an application that shows the current screen orientation to the user every time the screen orientation state changes:

Example 1
<!DOCTYPE html>
<html>
  <head>
    <title>Screen Orientation API Example 1</title>
    <script>
      function show() {
        alert("Screen orientation state is now " + screen.orientation);
      }

      screen.addEventListener("orientationchange", show);
      window.addEventListener("load", show);
    </script>
  </head>
  <body>
    <input type='button' value='Unlock'
      onclick='screen.unlockOrientation();'>
    <input type='button' value='Lock to portrait'
      onclick="screen.lockOrientation('portrait');">
    <input type='button' value='Lock to landscape'
      onclick="screen.lockOrientation('landscape');">
  </body>
</html>

2. Conformance

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 MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification 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].

3. Terminology

The EventHandler interface represents a callback used for event handlers as defined in [HTML5].

The concepts queue a task and fire a simple event are defined in [HTML5].
Unless specified otherwise, when queuing a task, the screen orientation task source is used.

The terms event handlers and event handler event types are defined in [HTML5].

The concepts of browsing context and active document are defined in [HTML5].

3.1 Current orientation

The current orientation is represented by one of the following values:

portrait-primary
The orientation is in the primary portrait mode.
portrait-secondary
The orientation is in the secondary portrait mode.
landscape-primary
The orientation is in the primary landscape mode.
landscape-secondary
The orientation is in the secondary landscape mode.

The concepts of primary orientation and secondary orientation depends on the device and the platform. Some devices are in portrait mode when the user holds the device in the normal orientation, other devices are in landscape mode when the user holds the device in its normal orientation. For devices whose normal orientation is a landscape mode, that normal orientation SHOULD be represented as landscape-primary. For devices whose normal orientation is a portrait mode, that normal orientation SHOULD be represented as portrait-primary. In both if the device is in landscape-primary and is rotated 90 degrees clockwise, that SHOULD be represented as portrait-primary.

3.2 Allowed orientations

The allowed orientations are represented by the following values:

portrait-primary
The orientation is in the primary portrait mode.
portrait-secondary
The orientation is in the secondary portrait mode.
landscape-primary
The orientation is in the primary landscape mode.
landscape-secondary
The orientation is in the secondary landscape mode.
portrait
The orientation is either portrait-primary or portrait-secondary.
landscape
The orientation is either landscape-primary or landscape-secondary.

3.3 Locking the orientation

To lock the orientation means forcing the rendering of the current browsing context to behave as if the screen was naturally orientated in a given orientation and will only change orientation to a given set of allowed orientations, regardless of the actual screen orientation relative to the user or the previous locks.

If the lock is done on only one orientation, the screen orientation MUST stay on the given orientation and never change until the screen orientation is locked again. Otherwise, the screen orientation MUST be able to change from an orientation to another as long as the orientations are amongst an orientation it has been locked to.

When the lock is done, if the orientation actually changed, the user agent MUST fire a simple event named orientationnchange at the Screen object.

3.4 Supported orientations

The supported orientations is a set of orientations that a user agent can lock the orientation to.

3.5 Default orientation

The browsing context's default orientation is the set of orientations to which the screen orientation would be locked when it is not explicitly locked by the current browsing context.

4. Extensions to the Screen Interface

The CSSOM View specification defines a Screen interface [CSSOM-VIEW], which this specification extends: 
partial interface Screen : EventTarget {
    readonly    attribute DOMString    orientation;
    boolean lockOrientation ((DOMString or sequence<DOMString>) orientations);
    void    unlockOrientation ();
                attribute EventHandler onorientationchange;
};

The orientation attribute MUST return the value representing the orientation of the screen. The returned orientation MUST be in the current orientation list.

The lockOrientation() method, when invoked, MUST run the steps for locking the screen orientation. If lockOrientation was called with a sequence of strings, the sequence MUST be used as orientation in the mentioned steps. Otherwise, the passed string MUST be the only element in orientations. The method MUST return the result returned from running previous steps.

The unlockOrientation() method, when invoked, MUST asynchronously lock the orientation to the default orientation. The user agent MAY ignore this call if the screen is already locked to the default orientation.

When the screen orientation changes in the current browsing context, the user agent MUST queue a task which updates the orientation attribute and fire a simple event named orientationchange at the Screen object.

Note

For example, that means if an application A is locked to landscape-primary and application B is locked to portrait-primary, switching from application A to B or B to A will not fire an orientationchange event because both applications will keep the orientation they had.

However, locking the orientation can fire an orientationchange if the orientation had to be changed to satisfy the lock requirements.

4.1 Locking the screen orientation

The steps for locking the screen orientation are as follows:

  1. If the user agent does not allow the current browsing context to lock the screen orientation, the steps MUST stop here and return false. For example, a user agent might only allow browsing context in a fullscreen state to lock the screen orientation or browsing context with elevated privileges.
  2. Let orientations be the list of locking orientations.
  3. For each orientation in the orientations list, run the following sub steps:
    1. If orientation isn't part of the allowed orientations, the steps MUST stop here and return false.
    2. If orientation is portrait or landscape the value MUST be removed from orientations and every allowed orientations it is representing MUST be inserted in orientations.
  4. If orientations isn't a supported orientations set, the steps MUST stop here and return false.
  5. Return true and run the remaining steps asynchronously.
  6. The user agent MUST lock the orientation to orientations.

5. Declarative orientation locking

This section is non-normative.

This specification doesn't intend to specify a declarative orientation locking. However, other specifications specify ways to do that.

The Web Application Manifest Format and Management APIs [WEBAPPS-MANIFEST-API] specifies a way to declare a default orientation for a web application inside the manifest file. That specification tries to follow this specification regarding orientation keywords.

The CSS Device Adaptation specification [CSS-ADAPTATION] specifies a way to declare a default orientation for a web page. That specification isn't yet in sync with this specification.

6. Event handlers

The following are the event handlers (and their corresponding event handler event types) that MUST be supported as attributes by the Screen object:

event handler event handler event type
onorientationchange orientationchange

A. Acknowledgments

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.

B. References

B.1 Normative references

[CSS-ADAPTATION]
Rune Lillesveen. CSS Device Adaptation. 15 September 2011. W3C Working Draft. URL: http://www.w3.org/TR/css-device-adapt/
[CSSOM-VIEW]
Simon Pieters; Glenn Adams. CSSOM View Module. 17 December 2013. W3C Working Draft. URL: http://www.w3.org/TR/cssom-view/
[HTML5]
Robin Berjon; Steve Faulkner; Travis Leithead; Erika Doyle Navara; Edward O'Connor; Silvia Pfeiffer. HTML5. 4 February 2014. W3C Candidate Recommendation. URL: http://www.w3.org/TR/html5/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[WEBAPPS-MANIFEST-API]
Anant Narayanan. Web Application Manifest Format and Management APIs. 30 January 2013. W3C Editor's Draft. URL: https://dvcs.w3.org/hg/app-manifest/raw-file/tip/index.html
[WEBIDL]
Cameron McCormack. Web IDL. 19 April 2012. W3C Candidate Recommendation. URL: http://www.w3.org/TR/WebIDL/