1 | # Cordova Screen Orientation Plugin
|
2 |
|
3 | Cordova plugin to set/lock the screen orientation in a common way for iOS, Android, WP8 and Blackberry 10. This plugin is based on an early version of [Screen Orientation API](http://www.w3.org/TR/screen-orientation/) so the api does not currently match the current spec.
|
4 |
|
5 | The plugin adds the following to the screen object:
|
6 |
|
7 | __lockOrientation(ORIENTATION_STRING)__
|
8 | lock the device orientation
|
9 |
|
10 | __unlockOrientation()__
|
11 | unlock the orientation
|
12 |
|
13 | __orientation__
|
14 | current orientation (ORIENTATION_STRING)
|
15 |
|
16 | ## Install
|
17 |
|
18 | cordova < 4
|
19 |
|
20 | cordova plugin add net.yoik.cordova.plugins.screenorientation
|
21 |
|
22 | cordova > 4
|
23 |
|
24 | cordova plugin add cordova-plugin-screen-orientation
|
25 |
|
26 | ## Supported Orientations
|
27 |
|
28 | __portrait-primary__
|
29 | The orientation is in the primary portrait mode.
|
30 |
|
31 | __portrait-secondary__
|
32 | The orientation is in the secondary portrait mode.
|
33 |
|
34 | __landscape-primary__
|
35 | The orientation is in the primary landscape mode.
|
36 |
|
37 | __landscape-secondary__
|
38 | The orientation is in the secondary landscape mode.
|
39 |
|
40 | __portrait__
|
41 | The orientation is either portrait-primary or portrait-secondary (sensor).
|
42 |
|
43 | __landscape__
|
44 | The orientation is either landscape-primary or landscape-secondary (sensor).
|
45 |
|
46 | ## Usage
|
47 |
|
48 | // set to either landscape
|
49 | screen.lockOrientation('landscape');
|
50 |
|
51 | // allow user rotate
|
52 | screen.unlockOrientation();
|
53 |
|
54 | // access current orientation
|
55 | console.log('Orientation is ' + screen.orientation);
|
56 |
|
57 | ## Events
|
58 |
|
59 | Both android and iOS will fire the orientationchange event on the window object.
|
60 | For this version of the plugin use the window object if you require notification.
|
61 |
|
62 |
|
63 | For this plugin to follow the full API events should be fired on the screen object.
|
64 | iOS and BB10 do not currently support events on the _screen_ object so custom event
|
65 | handling will need to be added (Suggestions welcome!).
|
66 |
|
67 | ## Android Notes
|
68 |
|
69 | The __screen.orientation__ property will not update when the phone is [rotated 180 degrees](http://www.quirksmode.org/dom/events/orientationchange.html).
|
70 |
|
71 | ## iOS Notes
|
72 |
|
73 | The iOS version is a combination of the cordova JS callback _window.shouldRotateToOrientation_ and the workaround to recheck the orientation as implemented in https://github.com/Adlotto/cordova-plugin-recheck-screen-orientation.
|
74 |
|
75 | __If you have a custom implementation of the _window.shouldRotateToOrientation_ it will have to be removed for the plugin to function as expected.__
|
76 |
|
77 | #### iOS6
|
78 |
|
79 | There has been a few cases where the rotation does not change the width of the viewport
|
80 |
|
81 | Issue [#1](https://github.com/gbenvenuti/cordova-plugin-screen-orientation/issues/1) @dokterbob
|
82 |
|
83 | >It seems to be related to having width=device-width, height=device-height in the meta viewport (which is part of the boilerplate phonegap/cordova app). It can be solved by updating the viewport with width=device-height, height=device-width or simply removing width and height altogether.
|
84 |
|
85 | #### iOS8
|
86 |
|
87 | Versions prior to 1.2.0 will cause an application crash in iOS8 due to a change in presentViewController timing.
|
88 |
|
89 | ## BB10 Notes
|
90 |
|
91 | Wraps the com.blackberry.app plugin functions, auto installed as a dependancy.
|
92 |
|
93 | ## WP8 Notes
|
94 |
|
95 | Windows phone does not support specification or primary and secondary orientations. If called with a specific orientation the plugin will just apply the landscape or portait orientation.
|
96 |
|
97 | # Changelog
|
98 |
|
99 | ## 1.3.5-6
|
100 | * Plugin added to npm
|
101 |
|
102 | ## 1.3.4
|
103 | * Readme update
|
104 |
|
105 | ## 1.3.3
|
106 | * [#53](https://github.com/gbenvenuti/cordova-plugin-screen-orientation/pull/53) WP8 Support
|
107 |
|
108 | ## 1.3.2
|
109 |
|
110 | * [#33](https://github.com/gbenvenuti/cordova-plugin-screen-orientation/issues/33) iOS8 Delay Block
|
111 |
|
112 | ## 1.3.0
|
113 |
|
114 | * [#23](https://github.com/gbenvenuti/cordova-plugin-screen-orientation/issues/23) iOS8 flicker
|
115 |
|
116 | ## 1.2.0-1.2.1
|
117 |
|
118 | * [#19](https://github.com/gbenvenuti/cordova-plugin-screen-orientation/issues/19) iOS8 Crash
|
119 |
|
120 |
|
121 |
|
122 | Pull requests welcome.
|