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.

Introduction

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>

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]].

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]].

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.

Allowed orientations

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

Extensions to the Screen Interface

TODO: should be 'partial interface' but respec doesn't support that.

The CSSOM View specification defines a Screen interface [[!CSSOM-VIEW]], which this specification extends:
readonly attribute DOMString orientation

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

The returned orientation MUST be in the current orientation list.

boolean lockOrientation(DOMtring orientation)
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.
void 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.

[TreatNonCallableAsNull] attribute Function? onorientationchange

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.

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

Acknowledgements

Many thanks to Jonas Sicking and Chris Jones for their contributions to the design of this specification.
Related searches:
screen primary landscape portrait secondary
gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.