The Screen Orientation API

3.1 Extensions to the Screen interface

partial interface Screen {
  [SameObject] readonly attribute ScreenOrientation orientation;
};

The orientation object is an instance of ScreenOrientation, which is described below.

3.2 ScreenOrientation interface

[Exposed=Window]
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.

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

3.3 OrientationType enum

enum OrientationType {
  "portrait-primary",
  "portrait-secondary",
  "landscape-primary",
  "landscape-secondary"
};

3.4 OrientationLockType enum

enum OrientationLockType {
  "any",
  "natural",
  "landscape",
  "portrait",
  "portrait-primary",
  "portrait-secondary",
  "landscape-primary",
  "landscape-secondary"
};

4.1 Reading the screen orientation

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.

The steps to update the orientation information of a document are as follows:

1. If the screen width is greater than the screen height, set the document's current orientation type to landscape-primary or landscape-secondary.
2. Otherwise, if the screen width is less than or equal to the screen height, set the document's current orientation type to portrait-primary or portrait-secondary.
3. Set the document's current orientation angle to the clockwise angle in degrees between the orientation of the viewport as it is drawn and the natural orientation of the device (i.e., the top of the physical screen). This is the opposite of the physical rotation. In other words, if a device is turned 90 degrees on the right, the current orientation angle would be 270 degrees.

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 current orientation type and the current orientation angle relation consistent for any given document.

4.2 Locking the screen orientation

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:

1. If the user agent does not support locking the screen orientation, return a promise rejected with a DOMException whose name is NotSupportedError and abort these steps.
2. The following sub-steps MAY be run asynchronously for performance reasons, for example, if the user agent has browsing contexts living in different processes:
   1. Let browsing contexts be the list of the descendant browsing contexts of the top-level browsing context's document.
   2. If one of the browsing contexts's document's pending promise is not null:
      1. Let doc be the document which has a not null pending promise.
      2. Reject doc's pending promise with DOMException whose name is AbortError.
      3. Set doc's pending promise to null .
3. If the document's active sandboxing flag set has the sandboxed orientation lock browsing context flag set, or user agent doesn't meet the security conditions to perform an orientation change, return a promise rejected with a DOMException whose name is SecurityError and abort these steps.
4. Let orientations be an empty list.
5. Depending on orientation value, do the following:

   portrait-primary or portrait-secondary or landscape-primary or landscape-secondary

   Append orientation to orientations.

   landscape

   Depending on platform convention, append landscape-primary, or landscape-secondary, or both to orientations.

   portrait

   Depending on platform convention, append portrait-primary, or portrait-secondary, or both to orientations.

   natural

   Append portrait-primary or landscape-primary to orientations such as the associated current orientation angle is 0.

   any

   Append portrait-primary, portrait-secondary, landscape-primary and landscape-secondary to orientations.

6. Set doc's pending promise to a newly-created promise.
7. Return doc's pending promise and continue asynchronously.
8. Lock the orientation of the document to orientations.
9. If locking the orientation did not result in a change of orientation, as part of the next animation frame task, resolve pending-promise with 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:

1. Set the document's orientation lock to orientations.
2. If the active orientation lock is not the document's orientation lock, abort these steps.
3. If the active orientation lock value is equal to orientations value, abort these steps.
4. If orientations contains only one value, run the following sub-steps:
   1. Let orientation be the value contained in orientations.
   2. Change how the viewport is drawn so that the document's current orientation type will be equal to orientation.
   3. After the change has happened, prevent the document's top-level browsing context's screen orientation from changing until those steps are run again.
   4. Abort these steps.
5. If the document's current orientation type is not part of orientations, change how the viewport is drawn such as the document's current orientation type will be equal to one of orientations' values.
6. Otherwise, depending on platform conventions, change how the viewport is drawn in order to make it match another screen orientation type. However, it has to be part of orientations.
7. Allow the user to change the screen orientation to any value part of orientations and only those values until those steps are run again. The method to define the current screen orientation has to match the platform conventions.

4.3 Screen orientation lock lifetime

To determine the active orientation lock, the user agent MUST run the following steps:

1. If there is only one top-level browsing context with a document that is visible per [PAGE-VISIBILITY], the active orientation lock is the document's orientation lock.
2. Otherwise, if there are more than one top-level browsing context with a document that is visible per [PAGE-VISIBILITY] but only one of those documents is focused, the active orientation lock is the focused document's orientation lock.
3. Otherwise, the active orientation lock SHOULD be the latest focused document's orientation lock, unless stated otherwise by the platform conventions.

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.

4.4 Handling screen orientation changes

Whenever the viewport's angle changes, the user agent MUST run the following steps as part of the next animation frame task:

1. Let browsing contexts be the list of the descendant browsing contexts of the top-level browsing context's document.
2. For each browsing context in browsing contexts, run the following sub-steps:
   1. Let doc be the browsing context's active document.
   2. If doc is not visible per [PAGE-VISIBILITY], abort these steps.
   3. Update the orientation information of doc.
   4. If doc's pending promise is not null:
      1. Resolve doc's pending promise with undefined.
      2. Set doc's pending promise to null .
   5. If the orientation change was triggered by a user gesture such as the user turning the device, as opposed to a call to lock, the task MUST be annotated with process user orientation change when running the next step.
   6. Fire an event named 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 run the following substeps as part of the next animation frame task:

1. Let type and angle be respectively the document's current orientation type and current orientation angle.
2. Update the orientation information of the document.
3. If type is different from the document's current orientation type or angle from the document 's current orientation angle, run the following sub-steps:
   1. If the document's pending promise is not null:
      1. Resolve the document's pending promise with undefined.
      2. Set the document's pending promise to null.
   2. If the orientation change was triggered by a user gesture such as the user turning the device, as opposed to a call to lock, the task MUST be annotated with process user orientation change when running the next step.
   3. Fire an event named change at the document's screen.orientation object.

An algorithm is triggered by a user generated orientation change if the task in which the algorithm is running is annotated with process user orientation change.

4.5 Default orientation

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.

5.1 Interaction with Fullscreen API

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 is not null. When that security condition applies, whenever the document's fullscreen element 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.