diff options
Diffstat (limited to 'tools/addon-sdk-1.7/packages/api-utils/docs/event')
-rw-r--r-- | tools/addon-sdk-1.7/packages/api-utils/docs/event/core.md | 51 | ||||
-rw-r--r-- | tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md | 95 |
2 files changed, 146 insertions, 0 deletions
diff --git a/tools/addon-sdk-1.7/packages/api-utils/docs/event/core.md b/tools/addon-sdk-1.7/packages/api-utils/docs/event/core.md new file mode 100644 index 0000000..6ab3317 --- /dev/null +++ b/tools/addon-sdk-1.7/packages/api-utils/docs/event/core.md @@ -0,0 +1,51 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> + +Module provides core (low level) API for working with events in the SDK. This +API is mainly for implementing higher level event APIs. + +Event `listener` may be registered on any (event `target`) object using +provided `on` function: + + var { on, once, off, emit } = require('api-utils/event/core'); + var target = { name: 'target' }; + on(target, 'message', function listener(event) { + console.log('hello ' + event); + }); + on(target, 'data', console.log); + +Event of specific `type` may be emitted on any event `target` object using +`emit` function. This will call all registered `listener`s for the given `type` +on the given event `target` in the same order they were registered. + + emit(target, 'message', 'event'); + // info: 'hello event' + emit(target, 'data', { type: 'data' }, 'second arg'); + // info: [Object object] 'second arg' + +Registered event listeners may be removed using `off` function: + + off(target, 'message'); + emit(target, 'message', 'bye'); + // info: 'hello bye' + +Sometimes listener only cares about first event of specific `type`. To avoid +hassles of removing such listeners there is convenient `once` function: + + once(target, 'load', function() { + console.log('ready'); + }); + emit(target, 'load') + // info: 'ready' + emit(target, 'load') + +There are also convenient ways to remove registered listeners. All listeners of +the specific type can be easily removed (only two argument must be passed): + + off(target, 'message'); + +Also, removing all registered listeners is possible (only one argument must be +passed): + + off(target); diff --git a/tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md b/tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md new file mode 100644 index 0000000..96feb79 --- /dev/null +++ b/tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md @@ -0,0 +1,95 @@ +<!-- This Source Code Form is subject to the terms of the Mozilla Public + - License, v. 2.0. If a copy of the MPL was not distributed with this + - file, You can obtain one at http://mozilla.org/MPL/2.0/. --> + +Provides an exemplar `EventTarget` object, that implements interface for +adding removing event listeners of a specific type. `EventTarget` is a +base of all objects in SDK on which events are emitted. + +### Instantiation + +It's easy to create event target objects, no special arguments are required. + + const { EventTarget } = require('api-utils/event/target'); + let target = EventTarget.new(); + +For a convenience though optional `options` arguments may be used, in which +case all the function properties with keys like: `onMessage`, `onMyEvent`... +will be auto registered for associated `'message'`, `'myEvent'` events on +the created instance. _All other properties of `options` will be ignored_. + +### Adding listeners + +`EventTarget` interface defines `on` method, that can be used to register +event listeners on them for the given event type: + + target.on('message', function onMessage(message) { + // Note: `this` pseudo variable is an event `target` unless + // intentionally overridden via `.bind()`. + console.log(message); + }); + +Sometimes event listener may care only about very first event of specific +`type`. `EventTarget` interface defines convenience method for adding one +shot event listeners via method `once`. Such listeners are called only once +next time event of the specified type is emitted: + + target.once('ready', function onReady() { + // Do the thing once ready! + }); + +### Removing listeners + +`EventTarget` interface defines API for unregistering event listeners, via +`removeListener` method: + + target.removeListener('message', onMessage); + +### Emitting events + +`EventTarget` interface intentionally does not defines an API for emitting +events. In majority of cases party emitting events is different from party +registering listeners. In order to emit events one needs to use `event/core` +module instead: + + let { emit } = require('api-utils/event/core'); + + target.on('hi', function(person) { console.log(person + 'tells hi'); }); + emit(target, 'hi', 'Mark'); + // info: 'Mark tells hi' + +For more details see **event/core** documentation. + +### More details + +Listeners registered during the event propagation (by one of the listeners) +won't be triggered until next emit of the matching type: + + let { emit } = require('api-utils/event/core'); + + target.on('message', function onMessage(message) { + console.log('listener trigerred'); + target.on('message', function() { + console.log('nested listener triggered'); + }); + }); + + emit(target, 'message'); + // info: 'listener trigerred' + emit(target, 'message'); + // info: 'listener trigerred' + // info: 'nested listener trigerred' + +Exceptions in the listeners can be handled via `'error'` event listeners: + + target.on('boom', function() { + throw Error('Boom!'); + }); + target.once('error', function(error) { + console.log('caught an error: ' + error.message); + }); + emit(target, 'boom'); + // info: caught an error: Boom! + +If there is no listener registered for `error` event or if it also throws +exception then such exceptions are logged into a console. |