Merge pull request #7 from gbenvenuti/screenOrientationApi

Screen orientation api

README.md

@@ -1,20 +1,62 @@
 #cordova-yoik-screenorientation
 
-Cordova plugin to set/lock the screen orientation in a common way for both iOS and Android.
+Cordova plugin to set/lock the screen orientation in a common way for both iOS and Android.  From version 1.0.0 the
+interface is based on the [Screen Orientation API](http://www.w3.org/TR/screen-orientation/).
 
 ##Install
 
-cordova plugin add https://github.com/yoik/cordova-yoik-screenorientation
+cordova plugin add net.yoik.cordova.plugins.screenorientation
 
-###Android
+###Source
+https://github.com/yoik/cordova-yoik-screenorientation
 
-The android version is implemented via the standard _activity.setRequestedOrientation_ as used in other screen orientation plugins
 
-###iOS
+##Orientations
+
+__portrait-primary__
+The orientation is in the primary portrait mode.
+
+__portrait-secondary__
+The orientation is in the secondary portrait mode.
+
+__landscape-primary__
+The orientation is in the primary landscape mode.
+
+__landscape-secondary__
+The orientation is in the secondary landscape mode.
+
+##Usage
+
+    screen.lockOrientation('landscape');
+
+    screen.unlockOrientation();
+
+##Events
+
+Both android and iOS will fire the orientationchange event on the window object.
+For this version of the plugin use the window object if you require notification.
+
+i.e.
+
+    function init() {
+        window.addEventListener("orientationchange", orientationChange, true);
+    }
+
+    function orientationChange(e) {
+        var orientation="portrait";
+        if(window.orientation == -90 || window.orientation == 90) orientation = "landscape";
+        document.getElementById("status").innerHTML+=orientation+"<br>";
+    }
+
+For this plugin to follow the API events should be fired on the screen object.
+iOS does not currently support events on the _screen_ object so custom event
+handling will need to be added (Suggestions welcome!).
+
+##iOS Notes
 
 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.
 
-If you have a custom impelemntation of the _window.shouldRotateToOrientation_ it will have to be removed for the plugin to function as expected.
+__If you have a custom implementation of the _window.shouldRotateToOrientation_ it will have to be removed for the plugin to function as expected.__
 
 ####iOS6
 
@@ -24,30 +66,5 @@ Issue [#1](https://github.com/yoik/cordova-yoik-screenorientation/issues/1) @dok
 
 >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.
 
-Constants
-====
-    Orientation: {
-        UNSPECIFIED: "unspecified",
-        LANDSCAPE: "landscape",
-        PORTRAIT: "portrait",
-        USER: "user",
-        BEHIND: "behind",
-        SENSOR: "sensor",
-        NOSENSOR: "nosensor",
-        SENSOR_LANDSCAPE: "sensorLandscape",
-        SENSOR_PORTRAIT: "sensorPortrait",
-        REVERSE_LANDSCAPE: "reverseLandscape",
-        REVERSE_PORTRAIT: "reversePortrait",
-        FULL_SENSOR: "fullSensor"
-    }
 
-Usage
+Pull requests welcome.
-====
-
-    var so = cordova.plugins.screenorientation;
-
-    // with callbacks
-    so.setOrientation(successCallback, errorCallback, so.Orientation.PORTRAIT);
-
-    // no callbacks
-    so.setOrientation(so.Orientation.SENSOR_LANDSCAPE);

plugin.xml

@@ -2,7 +2,7 @@
 <plugin xmlns="http://www.phonegap.com/ns/plugins/1.0"
     xmlns:android="http://schemas.android.com/apk/res/android"
     id="net.yoik.cordova.plugins.screenorientation"
-    version="0.0.3">
+    version="1.0.0">
 
     <name>YoikScreenOrientation</name>
     <description>Yoik Screen Orientation Plugin</description>

src/android/net/yoik/cordova/plugins/screenorientation/YoikScreenOrientation.java

@@ -41,21 +41,13 @@ public class YoikScreenOrientation extends CordovaPlugin {
      * Screen Orientation Constants
      */
 
-    // Refer to
+    private static final String UNLOCKED = "unlocked";
-    // http://developer.android.com/reference/android/R.attr.html#screenOrientation
+    private static final String PORTRAIT_PRIMARY = "portrait-primary";
-
+    private static final String PORTRAIT_SECONDARY = "portrait-secondary";
-    private static final String UNSPECIFIED = "unspecified";
+    private static final String LANDSCAPE_PRIMARY = "landscape-primary";
-    private static final String LANDSCAPE = "landscape";
+    private static final String LANDSCAPE_SECONDARY = "landscape-secondary";
     private static final String PORTRAIT = "portrait";
-    private static final String USER = "user";
+    private static final String LANDSCAPE = "landscape";
-    private static final String BEHIND = "behind";
-    private static final String SENSOR = "sensor";
-    private static final String NOSENSOR = "nosensor";
-    private static final String SENSOR_LANDSCAPE = "sensorLandscape";
-    private static final String SENSOR_PORTRAIT = "sensorPortrait";
-    private static final String REVERSE_LANDSCAPE = "reverseLandscape";
-    private static final String REVERSE_PORTRAIT = "reversePortrait";
-    private static final String FULL_SENSOR = "fullSensor";
 
     @Override
     public boolean execute(String action, JSONArray args, CallbackContext callbackContext) {
@@ -84,40 +76,28 @@ public class YoikScreenOrientation extends CordovaPlugin {
 
             Activity activity = cordova.getActivity();
 
-            if (orientation.equals(UNSPECIFIED)) {
+            if (orientation.equals(UNLOCKED)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED);
-            } else if (orientation.equals(LANDSCAPE)) {
+            } else if (orientation.equals(LANDSCAPE_PRIMARY)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
-            } else if (orientation.equals(PORTRAIT)) {
+            } else if (orientation.equals(PORTRAIT_PRIMARY)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_PORTRAIT);
-            } else if (orientation.equals(USER)) {
+            } else if (orientation.equals(LANDSCAPE)) {
-                activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_USER);
-            } else if (orientation.equals(BEHIND)) {
-                activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_BEHIND);
-            } else if (orientation.equals(SENSOR)) {
-                activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR);
-            } else if (orientation.equals(NOSENSOR)) {
-                activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_NOSENSOR);
-            } else if (orientation.equals(SENSOR_LANDSCAPE)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE);
-            } else if (orientation.equals(SENSOR_PORTRAIT)) {
+            } else if (orientation.equals(PORTRAIT)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT);
-            } else if (orientation.equals(REVERSE_LANDSCAPE)) {
+            } else if (orientation.equals(LANDSCAPE_SECONDARY)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_REVERSE_LANDSCAPE);
-            } else if (orientation.equals(REVERSE_PORTRAIT)) {
+            } else if (orientation.equals(PORTRAIT_SECONDARY)) {
                 activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_REVERSE_PORTRAIT);
-            } else if (orientation.equals(FULL_SENSOR)) {
-                activity.setRequestedOrientation(ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR);
             }
 
             callbackContext.success();
             return true;
 
         } else {
-
             callbackContext.error("ScreenOrientation not recognised");
             return false;
         }
     }
-
 }

www/screenorientation.js

@@ -23,71 +23,72 @@ SOFTWARE.
  */
 var argscheck = require('cordova/argscheck'),
     exec = require('cordova/exec'),
-    Constants = {
+    Orientations = [
-        Orientation: {
+        'portrait-primary',
-            UNSPECIFIED: "unspecified",
+        // The orientation is in the primary portrait mode.
-            LANDSCAPE: "landscape",
+        'portrait-secondary',
-            PORTRAIT: "portrait",
+        // The orientation is in the secondary portrait mode.
-            USER: "user",
+        'landscape-primary',
-            BEHIND: "behind",
+        // The orientation is in the primary landscape mode.
-            SENSOR: "sensor",
+        'landscape-secondary',
-            NOSENSOR: "nosensor",
+        // The orientation is in the secondary landscape mode.
-            SENSOR_LANDSCAPE: "sensorLandscape",
+        'portrait',
-            SENSOR_PORTRAIT: "sensorPortrait",
+        // The orientation is either portrait-primary or portrait-secondary.
-            REVERSE_LANDSCAPE: "reverseLandscape",
+        'landscape'
-            REVERSE_PORTRAIT: "reversePortrait",
+    ],
-            FULL_SENSOR: "fullSensor"
+    currOrientation = 'unlocked';
-        }
-    },
-    currOrientation = Constants.Orientation.UNSPECIFIED;
 
 var orientationExports = {};
 
-// Tack on the orientation Constants to the base plugin.
+function setOrientation(orientation) {
-for (var key in Constants) {
+    currOrientation = orientation ? orientation : 'unlocked';
-    orientationExports[key] = Constants[key];
+    exec(null, null, "YoikScreenOrientation", "screenOrientation", ['set', currOrientation]);
 }
 
-orientationExports.setOrientation = function(successCallback, errorCallback, orientation) {
+function addScreenOrientationApi(obj) {
-    if (typeof successCallback == "string") {
+    if (obj.unlockOrientation || obj.lockOrientation) {
-        orientation = successCallback;
+        return;
-        successCallback = function(){};
-        errorCallback = function(){};
     }
 
-    currOrientation = orientation ? orientation : Constants.Orientation.UNSPECIFIED;
+    obj.lockOrientation = function(orientation) {
+        if (Orientations.indexOf(orientation) == -1) {
+            console.log('INVALID ORIENTATION', orientation);
+            return;
+        }
+        setOrientation(orientation);
+    };
 
-    exec(successCallback, errorCallback, "YoikScreenOrientation", "screenOrientation", ['set', currOrientation]);
+    obj.unlockOrientation = function() {
-};
+        setOrientation('unlocked');
+    };
+}
+
+addScreenOrientationApi(screen);
 
 // ios orientation callback/hook
 window.shouldRotateToOrientation = function(orientation) {
-    var o = Constants.Orientation;
     switch (currOrientation) {
-        case o.PORTRAIT:
+        case 'portrait':
-        case o.SENSOR_PORTRAIT:
+        case 'portrait-primary':
             if (orientation === 0) return true;
         break;
-        case o.LANDSCAPE:
+        case 'landscape':
-        case o.SENSOR_LANDSCAPE:
+        case 'landscape-primary':
             if (orientation === -90) return true;
         break;
-        case o.REVERSE_LANDSCAPE:
+        case 'landscape':
+        case 'landscape-secondary':
             if (orientation === 90) return true;
         break;
-        case o.REVERSE_PORTRAIT:
+        case 'portrait':
+        case 'portrait-secondary':
             if (orientation === 180) return true;
         break;
-        case o.FULL_SENSOR:
+        default:
-            return true;
-        break;
-        case o.SENSOR:
-        case o.UNSPECIFIED:
             if (orientation === -90 || orientation === 90 || orientation === 0) return true;
         break;
     }
-
     return false;
-}
+};
 
-module.exports = orientationExports;
+module.exports = {};