WebAPI/ScreenOrientation

Proposed API

 partial interface Screen {
   readonly attribute DOMString orientation;
            attribute Function onorientationchange;
   boolean lockOrientation(DOMString orientation);
      void unlockOrientation();
 }

The Screen object is a property of the Window object and has existed since DOM Level 0 (i.e. for a really long time). This API adds three new properties to the object.

The orientation attribute is either "landscape-primary", "landscape-secondary", "portrait-primary" or "portrait-secondary". The reason for these values rather than "upsidedown" or something similar is that some devices are by default in landscape mode (desktop/tablets) and some devices (most mobile) are by default in portrait mode. The values have the following meaning:

• "portrait-primary": If the device has an obvious primary orientation in portrait mode, this the value for that orientation. If there is no obvious primary portrait orientation due to landscape being the primary orientation for the device, this is the orientation if rotating the device 90 degrees clock-wise from the primary landscape mode.

• "landscape-primary": If the device has an obvious primary orientation in landscape mode, this is the value that orientation. If there is no obvious landscape orientation due to portrait being the primary orientation for the device, this is the orientation if rotating the device 90 degrees clock-wise from the primary portrait mode.

• "portrait-secondary": The portrait mode opposite of "portrait-primary".

• "landscape-secondary": The landscape mode opposite of "landscape-primary".

Whenever the device orientation changes, an "orientationchange" event is fired on the Screen object *before* the rotation happens.

The lockOrientation function takes any of the following values, or a comma-separated combination thereof: "landscape", "portrait", "landscape-primary", "landscape-secondary", "portrait-primary" or "portrait-secondary". "landscape" and "portrait" refer to "any landscape orientation" and "any portrait orientation" respectively.

The function returns false if locking to the requested direction isn't allowed and true otherwise. If false is returned then the function takes no other actions.

Security considerations

It could be annoying for a user if a page repeatedly sets the orientation using the lockOrientation function. It could even prevent the user from navigating away from the page since the location or the browser UI could be jumping around too fast.

We can either solve this by only allowing the orientation lock to be changed if we are in fullscreen mode, or in an app (which doesn't have navigation UI). Or we can add "spam" protection such that we only allow the orientation lock to be changed in response to a user action or if it hasn't been changed the last N seconds.