The Screen Orientation API provides an interface for web applications to access and lock the user's device's screen orientation state.
This examples is an application that shows the current screen orientation to the user every time the screen orientation state changes:
<!DOCTYPE html> <html> <script> function show() { alert("Screen orientation state is " + screen.orientation); } screen.addEventListener("orientationchange", show, false); show(); </script> </html>
This specification defines conformance criteria that apply to a single product: the user agent that implements the interfaces that it contains.
Implementations that use ECMAScript to expose the APIs defined in this specification must implement them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification [[!WEBIDL]].
The
Function
interface represents a function in the scripting
language being used as defined in [[!HTML5]].
The concepts queue a task and fire a simple event are defined in [[!HTML5]].
The terms event handlers and event handler event types are defined in [[!HTML5]].
The concepts of browsing context and active document are defined in [[!HTML5]].
The current orientation SHOULD be an orientation amongst those values:
portrait-primary
, if the orientation is in the primary portrait mode;portrait-secondary
, if the orientation is in the secondary portrait mode;landscape-primary
, if the orientation is in the primary landscape mode;landscape-secondary
, if the orientation is in the secondary landscape mode.
The notion of primary and secondary depends on the device and the platform. Usually, platforms have a way to distinguish
the two portrait and landscape orientations.
For example, on most phones, portrait-primary is going to be the orientation that is used when the phone
is in hand and secondary will be upside-down orientation. Also, landscape-primary will be the landscape orientation
that is a 90 degree orientation counter-clock and secondary the other one.
On tablets, landscape-primary will be the orientation used when the tablet is in hands.
The allowed orientations SHOULD be orientations amongst the current orientation list
or amongst those values:
portrait
, value that covers portrait-primary
and portrait-secondary
cases;
landscape
, value that covers landscape-primary
and landscape-secondary
cases;
TODO: should be 'partial interface' but respec doesn't support that.
The CSSOM View specification defines aScreen
interface [[!CSSOM-VIEW]], which this specification extends:
The user agent MUST return the value of the orientation of the output device.
The returned orientation MUST be in the current orientation list.
orientationnchange
at the Screen
object.
The user agent MUST disable the current lock applied on the screen with lockOrientation
.
If the current browsing context has a default orientation, the screen orientation SHOULD revert to that.
When the screen orientation changes in the current browsing context, the user agent MUST queue a task
which updates the
For example, that means if an application A is locked to
However, locking the application can fire an orientation
attribute and fire a simple event named orientationchange
at the Screen
object.
landscape-primary
and application B is locked to portrait-primary
, switching from
application A to B or B to A will not fire an orientationchange
event because both application will keep the orientation they had.
orientationchange
if the
application wasn't in the specified type before being locked.
The following are the event handlers (and their corresponding
event handler event types) that MUST be supported as attributes
by the Screen
object:
event handler | event handler event type |
---|---|
onorientationchange |
orientationchange |