1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/addon-sdk/source/lib/sdk/dom/events.js Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,139 @@
1.4 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.5 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.7 +
1.8 +"use strict";
1.9 +
1.10 +module.metadata = {
1.11 + "stability": "unstable"
1.12 +};
1.13 +
1.14 +// Utility function that returns copy of the given `text` with last character
1.15 +// removed if it is `"s"`.
1.16 +function singularify(text) {
1.17 + return text[text.length - 1] === "s" ? text.substr(0, text.length - 1) : text;
1.18 +}
1.19 +
1.20 +// Utility function that takes event type, argument is passed to
1.21 +// `document.createEvent` and returns name of the initializer method of the
1.22 +// given event. Please note that there are some event types whose initializer
1.23 +// methods can't be guessed by this function. For more details see following
1.24 +// link: https://developer.mozilla.org/En/DOM/Document.createEvent
1.25 +function getInitializerName(category) {
1.26 + return "init" + singularify(category);
1.27 +}
1.28 +
1.29 +/**
1.30 + * Registers an event `listener` on a given `element`, that will be called
1.31 + * when events of specified `type` is dispatched on the `element`.
1.32 + * @param {Element} element
1.33 + * Dom element to register listener on.
1.34 + * @param {String} type
1.35 + * A string representing the
1.36 + * [event type](https://developer.mozilla.org/en/DOM/event.type) to
1.37 + * listen for.
1.38 + * @param {Function} listener
1.39 + * Function that is called whenever an event of the specified `type`
1.40 + * occurs.
1.41 + * @param {Boolean} capture
1.42 + * If true, indicates that the user wishes to initiate capture. After
1.43 + * initiating capture, all events of the specified type will be dispatched
1.44 + * to the registered listener before being dispatched to any `EventTarget`s
1.45 + * beneath it in the DOM tree. Events which are bubbling upward through
1.46 + * the tree will not trigger a listener designated to use capture.
1.47 + * See [DOM Level 3 Events](http://www.w3.org/TR/DOM-Level-3-Events/#event-flow)
1.48 + * for a detailed explanation.
1.49 + */
1.50 +function on(element, type, listener, capture) {
1.51 + // `capture` defaults to `false`.
1.52 + capture = capture || false;
1.53 + element.addEventListener(type, listener, capture);
1.54 +}
1.55 +exports.on = on;
1.56 +
1.57 +/**
1.58 + * Registers an event `listener` on a given `element`, that will be called
1.59 + * only once, next time event of specified `type` is dispatched on the
1.60 + * `element`.
1.61 + * @param {Element} element
1.62 + * Dom element to register listener on.
1.63 + * @param {String} type
1.64 + * A string representing the
1.65 + * [event type](https://developer.mozilla.org/en/DOM/event.type) to
1.66 + * listen for.
1.67 + * @param {Function} listener
1.68 + * Function that is called whenever an event of the specified `type`
1.69 + * occurs.
1.70 + * @param {Boolean} capture
1.71 + * If true, indicates that the user wishes to initiate capture. After
1.72 + * initiating capture, all events of the specified type will be dispatched
1.73 + * to the registered listener before being dispatched to any `EventTarget`s
1.74 + * beneath it in the DOM tree. Events which are bubbling upward through
1.75 + * the tree will not trigger a listener designated to use capture.
1.76 + * See [DOM Level 3 Events](http://www.w3.org/TR/DOM-Level-3-Events/#event-flow)
1.77 + * for a detailed explanation.
1.78 + */
1.79 +function once(element, type, listener, capture) {
1.80 + on(element, type, function selfRemovableListener(event) {
1.81 + removeListener(element, type, selfRemovableListener, capture);
1.82 + listener.apply(this, arguments);
1.83 + }, capture);
1.84 +}
1.85 +exports.once = once;
1.86 +
1.87 +/**
1.88 + * Unregisters an event `listener` on a given `element` for the events of the
1.89 + * specified `type`.
1.90 + *
1.91 + * @param {Element} element
1.92 + * Dom element to unregister listener from.
1.93 + * @param {String} type
1.94 + * A string representing the
1.95 + * [event type](https://developer.mozilla.org/en/DOM/event.type) to
1.96 + * listen for.
1.97 + * @param {Function} listener
1.98 + * Function that is called whenever an event of the specified `type`
1.99 + * occurs.
1.100 + * @param {Boolean} capture
1.101 + * If true, indicates that the user wishes to initiate capture. After
1.102 + * initiating capture, all events of the specified type will be dispatched
1.103 + * to the registered listener before being dispatched to any `EventTarget`s
1.104 + * beneath it in the DOM tree. Events which are bubbling upward through
1.105 + * the tree will not trigger a listener designated to use capture.
1.106 + * See [DOM Level 3 Events](http://www.w3.org/TR/DOM-Level-3-Events/#event-flow)
1.107 + * for a detailed explanation.
1.108 + */
1.109 +function removeListener(element, type, listener, capture) {
1.110 + element.removeEventListener(type, listener, capture);
1.111 +}
1.112 +exports.removeListener = removeListener;
1.113 +
1.114 +/**
1.115 + * Emits event of the specified `type` and `category` on the given `element`.
1.116 + * Specified `settings` are used to initialize event before dispatching it.
1.117 + * @param {Element} element
1.118 + * Dom element to dispatch event on.
1.119 + * @param {String} type
1.120 + * A string representing the
1.121 + * [event type](https://developer.mozilla.org/en/DOM/event.type).
1.122 + * @param {Object} options
1.123 + * Options object containing following properties:
1.124 + * - `category`: String passed to the `document.createEvent`. Option is
1.125 + * optional and defaults to "UIEvents".
1.126 + * - `initializer`: If passed it will be used as name of the method used
1.127 + * to initialize event. If omitted name will be generated from the
1.128 + * `category` field by prefixing it with `"init"` and removing last
1.129 + * character if it matches `"s"`.
1.130 + * - `settings`: Array of settings that are forwarded to the event
1.131 + * initializer after firs `type` argument.
1.132 + * @see https://developer.mozilla.org/En/DOM/Document.createEvent
1.133 + */
1.134 +function emit(element, type, { category, initializer, settings }) {
1.135 + category = category || "UIEvents";
1.136 + initializer = initializer || getInitializerName(category);
1.137 + let document = element.ownerDocument;
1.138 + let event = document.createEvent(category);
1.139 + event[initializer].apply(event, [type].concat(settings));
1.140 + element.dispatchEvent(event);
1.141 +};
1.142 +exports.emit = emit;
