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, 0 insertions, 146 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 deleted file mode 100644 index 6ab3317..0000000 --- a/tools/addon-sdk-1.7/packages/api-utils/docs/event/core.md +++ /dev/null @@ -1,51 +0,0 @@ -<!-- 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 deleted file mode 100644 index 96feb79..0000000 --- a/tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md +++ /dev/null @@ -1,95 +0,0 @@ -<!-- 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. |