all files / montage/composer/ key-composer.js

63.16% Statements 48/76
50.98% Branches 26/51
84.62% Functions 11/13
63.16% Lines 48/76
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341                                                                                                                32×     238×         238×                   32×             13× 13×                                   139×   139×   139× 139× 139×       139× 32× 31× 31×   107×                                                                                                                             154×   154×     154×     154×             154× 154×       154×   154×                                                                                                                                                     32×   32×                 31×                       13× 13×                           45×   45×     45×            
/**
 * @module montage/composer/key-composer
 * @requires montage/core/core
 * @requires montage/composer/composer
 */
var Montage = require("../core/core").Montage,
    Composer = require("./composer").Composer;
 
// Event types dispatched by KeyComposer
var KEYPRESS_EVENT_TYPE = "keyPress",
    LONGKEYPRESS_EVENT_TYPE = "longKeyPress",
    KEYRELEASE_EVENT_TYPE = "keyRelease";
 
/**
 * @class KeyComposer
 * @classdesc A `Composer` that makes it easy to listen for specific key
 * combinations and react to them.
 * @extends Composer
 * @fires keyPress
 * @fires longKeyPress
 * @fires keyRelease
 * @example
 * keyComposer = KeyComposer.createKey(textComponent, "command+z", "undo");
 * keyComposer.addEventListener("keyPress", undoManager);
 * // when command+z is pressed inside textComponent,
 * // undoManager.handleUndoKeyPress() will be called.
 */
var KeyComposer = exports.KeyComposer = Composer.specialize( /** @lends KeyComposer# */ {
 
    _shouldDispatchEvent: {
        value: false
    },
 
    shouldDispatchLongPress: {
        value: false
    },
 
    _longPressTimeout: {
        value: null
    },
 
    _keyRegistered: {
        value: false
    },
 
    _keys:{
        value: null
    },
 
    /**
     * The keyboard shortcut to listen to. One alphanumeric character or named
     * non-alphanumeric key, possibly with modifiers connected by '+'. The full
     * list of normalized keys and modifiers is in `KeyManager`.  @example "j",
     * "shift+j", "command+shift+j", "backspace", "win+pipe"
     * @type {string}
     * @default null
     */
    keys: {
        get: function () {
            return this._keys;
        },
        set: function (keys) {
            Iif (this._keyRegistered) {
                KeyManagerProxy.defaultKeyManager.unregisterKey(this);
                this._keys = keys;
                KeyManagerProxy.defaultKeyManager.registerKey(this);
            } else {
                this._keys = keys;
            }
        }
    },
 
    load: {
        value: function () {
            // Only register the key if somebody is listening for, else let do
            // it later.
            // console.log("--- load", this.identifier);
            if (this._shouldDispatchEvent && !this._keyRegistered) {
                KeyManagerProxy.defaultKeyManager.registerKey(this);
                this._keyRegistered = true;
            }
        }
    },
 
    unload: {
        value: function () {
            KeyManagerProxy.defaultKeyManager.unregisterKey(this);
            this._keyRegistered = false;
        }
    },
 
    /**
     * Listen to find out when this `KeyComposer` detects a matching key press.
     * @function
     * @param {string} type Any of the following types: keyPress, longKeyPress
     * and keyRelease.
     * @param {Object|function} listener The listener object or function to
     * call when dispatching the event.
     * @param {boolean} useCapture Specify if the listener want to be called
     * during the capture phase of the event.
     */
    addEventListener: {
        value: function (type, listener, useCapture) {
            // Optimisation so that we don't dispatch an event if we do not need to
            // console.log("--- addEventListener", this.identifier);
            var component = this.component;
 
            Composer.prototype.addEventListener.call(this, type, listener, useCapture);
 
            Eif (type == KEYPRESS_EVENT_TYPE || type == LONGKEYPRESS_EVENT_TYPE || type == KEYRELEASE_EVENT_TYPE) {
                this._shouldDispatchEvent = true;
                Iif (type == LONGKEYPRESS_EVENT_TYPE) {
                    this._shouldDispatchLongPress = true;
                }
 
                if (this._isLoaded) {
                    if (!this._keyRegistered) {
                        KeyManagerProxy.defaultKeyManager.registerKey(this);
                        this._keyRegistered = true;
                    }
                } else Iif (component && typeof component.addComposer !== "function") {
                    // this keyComposer is not associated with an element,
                    // let's make it a global key
                    if (!this.element) {
                        this.element = window;
                    }
                    // this keyComposer is not attached to a UI Component,
                    // let's load it manually
                    this.component.loadComposer(this);
                }
            }
        }
    },
 
    /**
     * Called when a composer is part of a template serialization. Responsible
     * for calling `addComposer` on the component or calling `load` on the
     * composer.
     * @private
     */
    deserializedFromTemplate: {
        value: function () {
            var component = this.component;
 
            if (this.identifier === null) {
                this.identifier = Montage.getInfoForObject(this).label;
            }
 
            if (component) {
                if (typeof component.addComposer == "function") {
                    component.addComposer(this);
                } else if (!this._isLoaded) {
                    // this keyComposer is not associated with an element,
                    // let's make it a global key
                    if (!this.element) {
                        this.element = window;
                    }
                    // this keyComposer is not attached to a UI Component,
                    // let's load it manually
                    this.component.loadComposer(this);
                }
            }
        }
    }
}, {
 
    /**
     * Constructs a `KeyComposer` to listen for a key combination on a
     * component.
     *
     * The composer will only respond to key events triggered by the DOM
     * elements inside its component or when its component is set as the
     * `activeTarget`.
     *
     * @param {Object} component The component to attach the `KeyComposer` to.
     * @param {Object} keys The key combination, possibly including modifier
     * keys.
     * @param {Object} identifier The identifier for events triggered by this
     * composer.
     * @returns {Object} the newly created `KeyComposer` Object
     */
    createKey: {
        value: function (component, keys, identifier) {
            var key = this;
 
            Eif (this === KeyComposer) {
                // This function has been called without creating a new
                // instance of KeyComposer first.
                key = new KeyComposer();
            }
 
            Iif (!identifier) {
                if (component.identifier) {
                    identifier = component.identifier + keys.toLowerCase().replace(/[ +]/g).toCapitalized();
                } else {
                    identifier = keys.toLowerCase().replace(/[ +]/g);
                }
            }
            key.keys = keys;
            key.identifier = identifier;
 
            // console.log("CREATING KEY:", component, key, key.identifier);
 
            component.addComposer(key);
 
            return key;
        }
    },
 
    /**
     * Constructs a `KeyComposer` listening for a key combination anywhere on
     * the page.
     *
     * The composer will respond to key events that bubble up to the `window`.
     *
     * @function
     * @param {Object} component. The component to attach the keyComposer to.
     * @param {Object} keys. The key sequence.
     * @param {Object} identifier. The identifier.
     * @returns {Object} the newly created KeyComposer Object
     */
    createGlobalKey: {
        value: function (component, keys, identifier) {
            var key = this;
 
            if (this === KeyComposer) {
                // This function has been called without creating a new
                // instance of KeyComposer first
                key = new KeyComposer();
            }
 
            key.keys = keys;
            key.identifier = identifier;
            // console.log("CREATING GLOBAL KEY:", component, key);
 
            component.addComposerForElement(key, window);
 
            return key;
        }
    }
 
});
 
 
/**
 * @class KeyManagerProxy
 * @classdesc Provide a proxy for lazy load of KeyManager.
 * @extends Montage
 * @private
 */
var _keyManagerProxy= null;
 
var KeyManagerProxy = Montage.specialize(  {
 
    /**
     * @private
     */
    _defaultKeyManager: {
        value: null
    },
 
    /**
     * @private
     */
    _loadingDefaultKeyManager: {
        value: false
    },
 
    /**
     * @private
     */
    _keysToRegister : {
        value: []
    },
 
    /**
     * Register a `KeyComposer` with the default `KeyManager`.
     * @function
     * @param {Object} keyComposer. A key composer object.
     */
    registerKey: {
        value: function (keyComposer) {
            var thisRef = this;
 
            if (!this._defaultKeyManager) {
                this._keysToRegister.push(keyComposer);
                Eif (!this._loadingDefaultKeyManager) {
                    this._loadingDefaultKeyManager = true;
 
                    require.async("core/event/key-manager")
                    .then(function (module) {
                        var keyManager = thisRef._defaultKeyManager = module.defaultKeyManager;
                        thisRef._keysToRegister.forEach(function (keyComposer) {
                            keyManager.registerKey(keyComposer);
                        });
                        thisRef._keysToRegister.length = 0;
                    });
                }
            } else {
                // This will happend only if somebody uses a cached return
                // value from KeyManagerProxy.defaultKeyManager
                this._defaultKeyManager.registerKey(keyComposer);
            }
        }
    },
 
    /**
     * Unregister a `KeyComposer` with the default `KeyManager`.
     * @function
     * @param {Object} keyComposer. A key composer object.
     */
    unregisterKey: {
        value: function (keyComposer) {
            Eif (this._defaultKeyManager) {
                this._defaultKeyManager.unregisterKey(keyComposer);
            }
        }
    }
 
}, {
 
    /**
     * Return either the default `KeyManager` or its `KeyManagerProxy`.
     * @function
     * @returns {Object} `KeyManager` or `KeyManagerProxy`.
     */
    defaultKeyManager: {
        get: function () {
            if (!_keyManagerProxy) {
                _keyManagerProxy = new KeyManagerProxy();
            }
            Iif (this._defaultKeyManager) {
                return this._defaultKeyManager;
            } else {
                return _keyManagerProxy;
            }
        }
    }
 
});