runtime-api.js - Runtime JS API

# Runtime JS API: runtime-api.js

API Docs for: 0.1

#### runtime-api.js

    /*
     * Copyright 2014 Canonical Ltd.
     *
     * This file is part of unity-webapps-qml.
     *
     * unity-webapps-qml is free software; you can redistribute it and/or modify
     * it under the terms of the GNU General Public License as published by
     * the Free Software Foundation; version 3.
     *
     * unity-webapps-qml is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     * GNU General Public License for more details.
     *
     * You should have received a copy of the GNU General Public License
     * along with this program.  If not, see <http://www.gnu.org/licenses/>.
     */

    /**
     * RuntimeApi gives access to the application runtime information and management.

     * @module RuntimeApi
     */
    function createRuntimeApi(backendBridge) {
        var PLUGIN_URI = 'RuntimeApi';

        function Application(id, content) {
            this._proxy = backendBridge.createRemoteObject(
                PLUGIN_URI, 'Application', id);

            this._name = content.name;
            this._platform = content.platform;
            this._writableLocation = content.writableLocation;
            this._screenOrientation = content.screenOrientation;
            this._inputMethodName = content.inputMethodName;

            this._setupPropertyListeners();
        };
        Application.prototype = {

            /**
             * Internal
             */
            _setupPropertyListeners: function() {
                var self = this;
                this._proxy.call('onApplicationNameChanged'
                                   , [function(name) {self._name = name;}]);
                this._proxy.call('onScreenOrientationChanged'
                                   , [function(orientation) {self._screenOrientation = orientation;}]);
            },

            /**
             * Retrieves the application name.
             *
             * @method getApplicationName
             * @return {String} application name
             */
            getApplicationName: function() {
                return this._name;
            },

            /**
             * Sets up a callback that is to be called when the application's name changed.
             *
             * @method onApplicationNameChanged
             * @param callback {Function(String)} Function to be called when the application's name has changed.
             */
            onApplicationNameChanged: function(callback) {
                var self = this;
                this._proxy.call('onApplicationNameChanged'
                                   , [callback]);
            },

            /**
             * Retrieves the fileystem location where the application is allowed to write its data in.
             *
             * @method getApplicationWritableLocation
             * @return {String} application writable location path
             */
            getApplicationWritableLocation: function() {
                return this._writableLocation;
            },

            /**
             * Retrieves current platform information.
             *
             * @method getPlatformInfos
             * @return {Object} platform information as a dictionary with the following keys:
             *  - name: the platform name
             */
            getPlatformInfo: function() {
                return this._platform;
            },

            /**
             * Sets up a callback that is to be called when the application is about to quit.
             *
             * @method onAboutToQuit
             * @param callback {Function()} Function to be called when the application is about to quit.
             */
            onAboutToQuit: function(callback) {
                this._proxy.call('onAboutToQuit'
                                   , [callback]);
            },

            /**
             * Sets up a callback that is to be called when the application has been deactivated (background).
             *
             * @method onDeactivated
             * @param callback {Function()} Function to be called when the application has been deactivated.
             */
            onDeactivated: function(callback) {
                this._proxy.call('onDeactivated'
                                   , [callback]);
            },

            /**
             * Sets up a callback that is to be called when the application has been activated (from background).
             *
             * @method onActivated
             * @param callback {Function()} Function to be called when the application has been activated.
             */
            onActivated: function(callback) {
                this._proxy.call('onActivated'
                                   , [callback]);
            },

            /**
             * Retrieves the current screen orientation.
             *
             * @method getScreenOrientation
             * @return {ScreenOrientation} current screen orientation.
             */
            getScreenOrientation: function() {
                return this._screenOrientation;
            },

            /**
             * Sets up a callback that is to be called when the application's screen has changed its orientation.
             *
             * @method onScreenOrientationChanged
             * @param callback {Function(ScreenOrientation)} Function to be called when the application's screen orientation has changed.
             */
            onScreenOrientationChanged: function(callback) {
                var self = this;
                this._proxy.call('onScreenOrientationChanged'
                                   , [callback]);
            },

            /**
             * Sets up a URI handler. The application can be sent URIs to open.
             *
             * @method setupUriHandler
             * @param callback {Function([String])} Function to be called with the current list of uris to open
             */
            setupUriHandler: function(callback) {
                this._proxy.call('setupUriHandler'
                                   , [callback]);
            },

            /**
             * Retrieves the current input method's name. The name varies depending on the platform
             * e.g. maliit can be part of the name for a maliit based Virtual Keyboard (possibly mangled
             * with e.g. 'phablet'), when a keyboard is there the name can be empty, ...
             *
             * @method getInputMethodName
             * @return {String} current input method name
             */
            getInputMethodName: function() {
                return this._inputMethodName;
            },

            /**
             * Sets up a callback that is to be called when the On Screen Keyboard visibility has changed.
             *
             * @method onInputMethodVisibilityChanged
             * @param callback {Function(Bool)} Function to be called when the On Screen Keyboard visibility has changed (received the visibility as an arg).
             */
            onInputMethodVisibilityChanged: function(callback) {
                this._proxy.call('onInputMethodVisibilityChanged'
                                   , [callback]);
            }
        };

        function _constructorFromName(className) {
            var constructorPerName = {
                "Application": Application,
            };
            return className in constructorPerName
                    ? constructorPerName[className]
                    : null;
        };

    /**
     * The RuntimeApi object

     * @class RuntimeApi
     * @constructor
     * @example

           var api = external.getUnityObject('1.0');
           api.RuntimeApi.getApplication(function(application) {
             console.log('Application name: ' + application.getApplicationName());
           });
     */
        return {
            /**
               Enumeration of the available types of ScreenOrientation.

                 Values:

                   Landscape: The application screen is in landscape mode

                   InvertedLandscape: The application screen is in inverted landscape mode

                   Portrait: The application screen is in portrait mode

                   InvertedPortrait: The application screen is in inverted portrait mode

                   Unknown: The application screen is in an unknown mode

               @static
               @property ScreenOrientation {Object}

               @example

                   var api = external.getUnityObject('1.0');
                   var orientation = api.RuntimeApi.ScreenOrientation;
                   // use orientation.Landscape or orientation.Portrait
             */
            ScreenOrientation: {
                Landscape: "Landscape",

                InvertedLandscape: "InvertedLandscape",

                Portrait: "Portrait",

                InvertedPortrait: "InvertedPortrait",

                Unknwon: "Unknown",
            },

            /**
             * Creates an Application object.
             *
             * @method getApplication
             * @param callback {Function (Application)}
             */
            getApplication: function(callback) {
                backendBridge.call('RuntimeApi.getApplication'
                                   , []
                                   , callback);
            },

            /**
             * @private
             *
             */
            createObjectWrapper: function(objectType, objectId, content) {
                var Constructor = _constructorFromName(objectType);
                return new Constructor(objectId, content);
            },
        };
    };