|
|
| (3 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| == Proposed API ==
| | This API is now a Working Draft at W3C (WebApps WG) so for any documentation, please refer to the specification:<br> |
| | https://dvcs.w3.org/hg/screen-orientation/raw-file/tip/Overview.html |
|
| |
|
| partial interface Screen {
| | [[Category:Web APIs]] |
| readonly attribute DOMString orientation;
| |
| attribute Function onorientationchange;
| |
| boolean lockOrientation(DOMString orientation);
| |
| }
| |
| | |
| | |
| The <code>Screen</code> 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 <code>orientation</code> attribute is either <code>"landscape-primary"</code>, <code>"landscape-secondary"</code>, <code>"portrait-primary"</code> or <code>"portrait-secondary"</code>. 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 <code>"orientationchange"</code> event is fired on the Screen object *before* the rotation happens.
| |
| | |
| The <code>lockOrientation</code> function takes any of the following values, or a comma-separated combination thereof: <code>"landscape"</code>, <code>"portrait"</code>, <code>"landscape-primary"</code>, <code>"landscape-secondary"</code>, <code>"portrait-primary"</code> or <code>"portrait-secondary"</code>. <code>"landscape"</code> and <code>"portrait"</code> refer to "any landscape orientation" and "any portrait orientation" respectively.
| |
| | |
| The function returns <code>false</code> if locking to the requested direction isn't allowed and <code>true</code> otherwise. If <code>false</code> 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.
| |