Module ringo/events

Exports an EventEmitter classes that provide methods to emit events and register event listener functions.

Class EventEmitter

Instance Methods

Class JavaEventEmitter

Instance Methods

Instance Properties


EventEmitter ()

This class provides methods to emit events and add or remove event listeners.

The EventEmitter function can be used as constructor or as mix-in. Use the new keyword to construct a new EventEmitter:

var emitter = new EventEmitter();

To add event handling methods to an existing object, call or apply the EventEmitter function with the object as this:

EventEmitter.call(object);

EventEmitter.prototype.emit (type, [args...])

Emit an event to all listeners registered for this event type

Parameters

string type type the event type
... [args...] optional arguments to pass to the listeners

Returns

true if the event was handled by at least one listener, false otherwise

Throws

Error if the event type was "error" and there were no listeners

EventEmitter.prototype.listeners (type)

Get an array containing the listener functions for the given event. If no listeners exist for the given event a new array is created. Changes on the return value will be reflected in the EventEmitter instance.

Parameters

string type the event type

Returns

array the lister array

EventEmitter.prototype.on (type, listener)

Add a listener function for the given event. This is a shortcut for addListener()

Parameters

string type the event type
function listener the listener

Returns

this object for chaining

EventEmitter.prototype.removeAllListeners (type)

Remove all listener function for the given event.

Parameters

string type the event type

Returns

this object for chaining

EventEmitter.prototype.removeListener (type, listener)

Remove a listener function for the given event.

Parameters

string type the event type
function listener the listener

Returns

this object for chaining

JavaEventEmitter (classOrInterface, eventMapping)

An adapter for dispatching Java events to Ringo. This class takes a Java class or interface as argument and creates a Java object that extends or implements the class or interface and forwards method calls to event listener functions registered using the EventEmitter methods.

Like EventEmitter, JavaEventEmitter can be used as constructor or as mix-in. Use the new keyword to construct a new JavaEventEmitter:

var emitter = new JavaEventEmitter(JavaClassOrInterface);

To add event handling methods to an existing object, call or apply the JavaEventEmitter function with the object as this:

JavaEventEmitter.call(object, JavaClassOrInterface);

JavaEventEmitter accepts an object as optional second argument that maps Java methods to event names. If the first argument is a Java class this mapping also allows to select which methods should be overridden. If called without event mapping the method name is used as event name, except for methods like onFoo which will trigger event foo.

Parameters

classOrInterface a Java class or interface, or an Array containing multiple Java interfaces.
eventMapping optional object mapping method names to event names. If this parameter is defined only methods whose name is a property key in the object will be overridden, and the event type will be set to the property value instead of the method name.

JavaEventEmitter.prototype.addListener (type, listener)

Add a listener function for the given event. The function will be called asynchronously on the thread of the local event loop.

Parameters

string type the event type
function listener the listener

JavaEventEmitter.prototype.addSyncListener (type, listener)

Add a synchronous listener function for the given event. A synchronous listener will be called by an outside thread instead of the thread of the local event loop. This means it can be called concurrently while this worker is running other code.

Parameters

string type the event type
function listener the listener

JavaEventEmitter.prototype.emit (type, [args...])

Emit an event to all listeners registered for this event type

Parameters

string type type the event type
... [args...] optional arguments to pass to the listeners

Returns

true if the event was handled by at least one listener, false otherwise

Throws

Error if the event type was "error" and there were no listeners

JavaEventEmitter.prototype.impl

The generated Java object. This implements the Java interface passed to the JavaEventEmitter constructor and can be passed to Java code that expects given interface.


JavaEventEmitter.prototype.on (type, listener)

Add a listener function for the given event. This is a shortcut for addListener()

Parameters

string type the event type
function listener the listener

JavaEventEmitter.prototype.removeListener (type, listener)

Remove a listener function for the given event.

Parameters

string type the event type
function listener the listener