|
|
| (One intermediate revision by one other user 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);
| |
| void unlockOrientation();
| |
| }
| |
| | |
| | |
| 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. The values have the following meaning:
| |
| | |
| * '''<code>"portrait-primary"</code>''': 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.
| |
| | |
| * '''<code>"landscape-primary"</code>''': 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.
| |
| | |
| * '''<code>"portrait-secondary"</code>''': The portrait mode opposite of "portrait-primary".
| |
| | |
| * '''<code>"landscape-secondary"</code>''': The landscape mode opposite of "landscape-primary".
| |
| | |
| | |
| 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.
| |