WebAPI/ScreenOrientation

Proposed API

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

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.

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.