IEventSource

Last updated
Save as PDF

pentaho .lang.IEventSource

The IEventSource interface represents objects that emit events.

The structure of events

Events are identified by their type and can be "structured" or not.

Structured events go through multiple phases, while unstructured events have no phases (or can be seen to have a single phase).

The following are examples of the phases of hypothetical structured events:

"before" and "after"
"capture" and "bubble"
"init", "success" and "failure"

The order and logic of occurrence of each of the phases is specific to each event and should be documented along with it. The occurrence of event phases can be conditional, and event phases can be synchronous or asynchronous.

Listening to events

Event observers are maps of event listener functions, one for each relevant phase of an event, and is used to register for the emissions of a structured event.

Event listener functions, which can be synchronous or asynchronous, are used to register for the emissions of an unstructured event.

The listener functions are called with a single object argument, that represents the specific event emission. The specific type of this argument is not mandated, however, the provided Event class is a reasonable choice for unstructured events, and is used for events of many of the Pentaho Platform JavaScript APIs' classes.

This interface exposes methods for the registration and unregistration of event observers (or listeners), on and off, respectively.

Source: doc-js/pentaho/lang/IEventSource.jsdoc, line 17

Example

// An hypothetical event source.
 var car = new MyCar();

 // Register for an unstructured event
 car.on("validate", function(ev) {
 // Do validation of this car instance.
 });

 // Register for a structured event
 car.on("start", {
 will: function(ev) {
 // About to start the engine.
 },
 did: function(ev) {
 // The engine has started!
 },
 });

Methods

Name	Description
off(typeOrHandle, observer)	Removes one registration given its handle, or all registrations of a given event type (or types) and observer (or listener function).
on(type, observer, keyArgs) : `pentaho.lang.IEventRegistrationHandle`	Registers an observer (or listener function) for an event(s) of a given type(s).

Methods Details

off(typeOrHandle, observer)

Removes one registration given its handle, or all registrations of a given event type (or types) and observer (or listener function).

To remove an event registration, it is sufficient to call the dispose method of the registration handle returned by on, upon registration. Alternatively, as a convenience syntax, the registration handle can be passed as the single argument to this method.

It is safe to unregister from an event type while it is being emitted. However, any registrations removed during the current emission will still execute.

Specifying an event registration handle that has already been disposed of has no effect. Specifying an event type and observer (or listener function) that have no registrations has no effect.

Source: doc-js/pentaho/lang/IEventSource.jsdoc, line 131

Parameters:
Name	Default Value	Summary
typeOrHandle : `nonEmptyString` \| `Array.<nonEmptyString>` \| `pentaho.lang.IEventRegistrationHandle`		The type or types of events, or an event registration handle to dispose of. When a string, it can be a comma-separated list of event types.
observer : `pentaho.lang.IEventObserver` \| `pentaho.lang.EventListener` \| `pentaho.lang.EventListenerAsync`		The event observer (or listener function). Required when `typeOrHandle` is not an event registration handle; ignored, otherwise.

See also: pentaho.lang.IEventSource#on

on(type, observer, keyArgs) : pentaho.lang.IEventRegistrationHandle

Registers an observer (or listener function) for an event(s) of a given type(s).

Optionally, a listening priority may be specified to adjust the order by which an observer is notified, relative to other listeners.

Note that if an observer is registered more than once to the same event type, a new registration is created each time and its listeners will be called once per registration.

It is safe to register for an event type while it is being emitted. However, new registrations are only taken into account in subsequent emissions.

When type represents multiple event types, the returned event registration handle is a composite registration for all of the event types.

This method is compatible with the dojo/on API.

Source: doc-js/pentaho/lang/IEventSource.jsdoc, line 90

Name Default Value Summary

type : nonEmptyString | Array.<nonEmptyString>

The type or types of events. When a string, it can be a comma-separated list of event types.

observer : pentaho.lang.IEventObserver | pentaho.lang.EventListener | pentaho.lang.EventListenerAsync

The event observer (or listener function).

keyArgs : object

Optional

Keyword arguments.

Parameters:
Name	Default Value	Summary
priority : `number` Optional	0	The listening priority. Higher priority observers are notified of an event before any lower priority observers. The priority can be set to `-Infinity` or `Infinity`. In case two observers are assigned the same priority, the registration order determines which is notified first.

Returns:
Name	Description
`pentaho.lang.IEventRegistrationHandle`	An event registration handle that can be used for later removal.

See also: pentaho.lang.IEventSource#off