diff options
Diffstat (limited to 'tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md')
-rw-r--r-- | tools/addon-sdk-1.7/packages/api-utils/docs/event/target.md | 95 |
1 files changed, 0 insertions, 95 deletions
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. |