W3C

The Screen Orientation API

W3C Working Draft 22 May 2012

This version:
http://www.w3.org/TR/2012/WD-screen-orientation-20120522/
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
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 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.

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: 

<!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 Function interface represents a function in the scripting language being used 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. Usually, platforms have a way to distinguish the two portrait and landscape orientations.
For example, on most phones, portrait-primary is going to be the orientation that is used when the phone is in hand and secondary will be upside-down orientation. Also, landscape-primary will be the landscape orientation that is a 90 degree orientation counter-clock and secondary the other one.
On tablets, landscape-primary will be the orientation used when the tablet is in hands.

3.2 Allowed orientations

The allowed orientations should be orientations amongst the current orientation list or amongst those values:

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 (DOMtring orientation);
    void    unlockOrientation ();
    [TreatNonCallableAsNull]
             attribute Function? onorientationchange;
};

4.1 Attributes

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

The user agent must return the value of the orientation of the output device.

The returned orientation must be in the current orientation list.

4.2 Methods

lockOrientation
The user agent must run these steps:
  1. If the orientation isn't part of the allowed orientations, the method must return false.
  2. If locking to orientation isn't currently allowed, the method must return false.
  3. Otherwise, the method must return true and the screen orientation should be locked to orientation.
When the lock is done, if the orientation did change, the user agent must fire a simple event named orientationnchange at the Screen object.
ParameterTypeNullableOptionalDescription
orientationDOMtring✘✘
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.

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.

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 application will keep the orientation they had.

However, locking the application can fire an orientationchange if the application wasn't in the specified type before being locked.

5. 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. Acknowledgements

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

B. References

B.1 Normative references

[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. 25 May 2011. 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
[WEBIDL]
Cameron McCormack. Web IDL. 27 September 2011. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2011/WD-WebIDL-20110927/

B.2 Informative references

No informative references.