Skip to content

Latest commit

 

History

History
247 lines (186 loc) · 10.2 KB

event.md

File metadata and controls

247 lines (186 loc) · 10.2 KB
Raw

Classes

EventProperty

Represents a certain kind of events. Provides methods to observe and to trigger(emit) that kind of events.

Beacon

Represents a model of a single property of type T. A basic element for constructing models.

  • Property can be retrieved/changed by using the .value property of the beacon.
  • Setting new value will trigger the 'changed' event.
  • Setting the same value will be ignored and won't trigger the 'changed' event.
  • Can sync to another beacon. Whenever the value of one of the synced beacons changes the value of the other is changed accordingly.
  • Attempt to get a value before it was assigned results in exception. It is better to pass initial value to the constructor

EventProperty

Represents a certain kind of events. Provides methods to observe and to trigger(emit) that kind of events.

Kind: global class

eventProperty.isInitialized ⇒ boolean

A special property, indicating that the event was emitted at least once.

Kind: instance property of EventProperty

eventProperty.emit(eventArg)

Emits event with given argument. This invokes all appropriate handlers.

Kind: instance method of EventProperty

Param Type Description
eventArg T event argument, it's passed to each event handler.

eventProperty.on(handler, [context]) ⇒ ListenerId

Adds a listener.

Kind: instance method of EventProperty
Returns: ListenerId - - number, identifying new event listener.

Param Type Description
handler Handler.<T> callback to be called when an event is emitted
[context] Object context to be used when calling handler. null by default.

eventProperty.once(handler, [context]) ⇒ ListenerId

Adds a listener. This listener will be immediately removed after it's invoked for the first time.

Kind: instance method of EventProperty
Returns: ListenerId - - number, identifying new event listener.

Param Type Default Description
handler Handler.<T> callback to be called when an event is emitted
[context] Object context to be used when calling handler. null by default.

eventProperty.match(value, handler, [context]) ⇒ ListenerId

Adds a listener. This listener will be invoked only if event argument matches given value.

Note: what "matching" means is not documented well yet since it is subject to change. For now you should assume that for plain types (boolean, number, string) it is strict equality. For objects it is like deep strict equality except that actual event argument may have more fields than match-value(proto). But all fields from match-value must be present in event argument.

Kind: instance method of EventProperty
Returns: ListenerId - - number, identifying new event listener.
See: objectMatch

Param Type Description
value T | RegExp handler is invoked only if event argument matches this value
handler Handler.<T> callback to be called when an event is emitted
[context] Object context to be used when calling handler. null by default.

eventProperty.matchOnce(value, handler, [context]) ⇒ ListenerId

Adds a listener for this event type. This listener will be invoked only if event argument matches given value. This listener will be immediately removed after it's invoked for the first time.

Note: what "matching" means is not documented well yet since it is subject to change. For now you should assume that for plain types (boolean, number, string) it is strict equality. For objects it is like deep strict equality except that actual event argument may have more fields than match-value(proto). But all fields from match-value must be present in event argument.

Kind: instance method of EventProperty
Returns: ListenerId - - number, identifying new event listener.
See: PropertyEvent.match, PropertyEvent.once

Param Type Default Description
value T | RegExp handler is invoked only if event argument matches this value
handler Handler.<T> callback to be called when an event is emitted
[context] Object context to be used when calling handler. null by default.

eventProperty.pipe(other) ⇒ ListenerId

"Pipes" EventProperty to other This means that whenever this event is emitted it is passed to that other EventProperty which emits it too.

Kind: instance method of EventProperty

Param Type
other EventProperty.<T>

eventProperty.route(matchValue, destination) ⇒ ListenerId

Pipe only events with matching argument to destination

Note: what "matching" means is not documented well yet since it is subject to change. For now you should assume that for plain types (boolean, number, string) it is strict equality. For objects it is like deep strict equality except that actual event argument may have more fields than match-value(proto). But all fields from match-value must be present in event argument.

Kind: instance method of EventProperty
See: pipe, match

Param Type Description
matchValue T | RegExp value to match
destination EventProperty.<T> target EventProperty

eventProperty.init(handler, [context])

Adds an initialization handler. Initialization handlers are invoked during the very first emit of event in this If first emit already occurred then the handler is invoked immediately. This method returns a promise which may be used instead of passing a callback. Note that promise resolve and reject handler will be invoked only on the next event loop iteration while callback which is passed directly will beb invoked immediately and before any event-listeners.

Kind: instance method of EventProperty

Param Type Description
handler Handler.<T> callback to be invoked when event is emitted first time
[context] Object handler will be invoked in this context

EventProperty.make()

Creates a pair: an EventProperty instance to be used internally in a class and an Emitter-interface to be used as public / accessible property. They both actually represent the same EventProperty object.

returns {[EventProperty,Emitter]}

Kind: static method of EventProperty

EventProperty.split()

Creates an EventProperty object and splits it into emitter-function and Emitter-interface. Use emitter function to emit the event and Emitter-interface to add and remove listeners of that event.

returns {[EmitMethod,Emitter]}

Kind: static method of EventProperty

EventProperty.splitVoid()

Creates an EventProperty object and splits it into emitter-function and Emitter-interface. Special version for void-typed events.

returns {[VoidEmitMethod,Emitter]}

Kind: static method of EventProperty

Beacon

Represents a model of a single property of type T. A basic element for constructing models.

  • Property can be retrieved/changed by using the .value property of the beacon.
  • Setting new value will trigger the 'changed' event.
  • Setting the same value will be ignored and won't trigger the 'changed' event.
  • Can sync to another beacon. Whenever the value of one of the synced beacons changes the value of the other is changed accordingly.
  • Attempt to get a value before it was assigned results in exception. It is better to pass initial value to the constructor

Kind: global class

.Void

Kind: static class
See: {EventProperty}

new Void()

Special subclass of EventProperty for void type - allows calling emit without arguments. Extends EventProperty

void.emit()

Emits an event invoking all listeners.

Kind: instance method of Void
See: {EventProperty#emit}