W3C

The Screen Orientation API

W3C Working Draft 06 December 2012

This version:
http://www.w3.org/TR/2012/WD-screen-orientation-20121206/
Latest published version:
http://www.w3.org/TR/screen-orientation/
Latest editor's draft:
http://dvcs.w3.org/hg/screen-orientation/raw-file/tip/Overview.html
Previous version:
http://www.w3.org/TR/2012/WD-screen-orientation-20120522/
Editor:
Mounir Lamouri, Mozilla

Copyright © 2012 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.

Abstract

The Screen Orientation API's goal is to provide an interface for web applications to be able 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 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) with [screen-orient] at the start of the subject header. A bug list for this document is available. 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.

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 user's 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>
  <script>
    function show() {
      alert("Screen orientation state is " + screen.orientation);
    }

    screen.addEventListener("orientationchange", show, false);

    show();
  </script>
</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].

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 should be an orientation amongst those values:

The notion of primary and secondary 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 should be orientations amongst those values:

3.3 Lock the orientation

The action to lock the orientation consists of forcing the rendering of the current browsing context to be shown as if the screen was oriented in one or many of the current orientation.
If the lock is done on only one orientation, the screen orientation should stay on the given orientation and never change until the screen orientation is unlocked. Otherwise, the screen orientation should be able to change from an orientation to another as long as the orientations are amongst an orientation it has been locked to.

3.4 Supported orientations

A set of orientations is said to be a supported orientation set if the user agent can lock the orientation to that set.

4. Extensions to the Screen Interface

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

4.1 Attributes

onorientationchange of type EventHandler, nullable
orientation of type DOMString, readonly

The user agent must return the value representing the orientation of the screen.

The returned orientation must be in the current orientation list.

4.2 Methods

lockOrientation
The method must run these steps for locking the screen orientation with orientation being the only locking orientation and return the value returned from those steps.
ParameterTypeNullableOptionalDescription
orientationDOMString✘✘
Return type: boolean
lockOrientation
The method must run these steps for locking the screen orientation with orientations being the only locking orientation and return the value returned from those steps.
ParameterTypeNullableOptionalDescription
orientationssequence<DOMString>✘✘
Return type: boolean
unlockOrientation

The user agent must disable the current lock applied on the screen with lockOrientation. If the current browsing context has a default orientation, the screen orientation should revert to that. Otherwise, the screen orientation should revert to any value the user agent believes appropriate.

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

No parameters.
Return type: void

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.3 Locking the screen orientation

The steps for locking the screen orientation are the following:

  1. Let orientations be the list of locking orientations.
  2. 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 should be removed from the list and the values it is representing must be inserted instead.
  3. If orientations isn't a supported orientation set, the steps must stop here and return false.
  4. Return true and run the remaining steps asynchronously.
  5. The user agent must lock the orientation to orientations.
  6. When the lock is done, if the orientation actually changed, the user agent must fire a simple event named orientationnchange at the Screen object.

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

Many thanks to Jonas Sicking and Chris Jones for their contributions to the design of this specification.

B. References

B.1 Normative references

[CSS-ADAPTATION]
Rune Lillesveen. CSS Device Adaptation. 23 January 2012. Editor's Draft. (Work in progress.) URL: http://dev.w3.org/csswg/css-device-adapt/
[CSSOM-VIEW]
Anne van Kesteren. CSSOM View Module. 22 February 2008. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2008/WD-cssom-view-20080222
[HTML5]
Ian Hickson; David Hyatt. HTML5. 29 March 2012. W3C Working Draft. (Work in progress.) 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. W3C Editor's Draft. (Work in progress.) URL: http://dvcs.w3.org/hg/app-manifest/raw-file/tip/index.html
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/