• OEvent or objx(o).event()
• Usage
• Example
• Event methods
• .oevent_listeners
• obj.oevent_listeners.onSomething array
• Event shortcut method
• obj.onSomething( function )
• obj.onSomething()
• Chaining with events
• Explicitly firing events - obj.fire_onSomething
• Explicitly listening for events - obj.listenFor_onSomething
• Removing callbacks
• Events in classes
• Tutorials

OEvent or objx(o).event()

Provides a simple eventing model to allow OO programmers to use eventing.

Usage

OEvent( object, eventName );

or

objx( object ).event( eventName );

object - The object to add the events to

eventName - (string) The name of the event

Example

// create a simple object
var myObject = {
  counter: 0
}

// add events
OEvent(myObject, "onCounterIncreased");
OEvent(myObject, "onCounterDecreased");

// add methods that make use of the events
myObject.increaseCounter = function(){ this.counter++; this.onCounterIncreased(); };
myObject.decreaseCounter = function(){ this.counter--; this.onCounterDecreased(); };

// add event listeners
myObject.onCounterIncreased(function(){ alert("Counter increased"); });
myObject.onCounterDecreased(function(){ alert("Counter decreased"); });

// use the methods and see the callbacks in action
myObject.increaseCounter();

// alerts "Counter increased"

myObject.decreaseCounter();

// alerts "Counter decreased"

Event methods

Once you have extended an object with OEvent you will be given access to a range of supporting functions and objects.

Creating an event called onSomething on object obj will generate the following items:

obj.oevent_listeners.onSomething - An array of callback listeners.

obj.onSomething - (function) Handy shortcut method for managing events.

obj.fire_onSomething - (function) Fires the event.

obj.listenFor_onSomething - (function) Adds a callback listener for the event.

obj.onSomething.forget - (function) Removes callback listeners from events.

.oevent_listeners

oevent_listeners is an object that contains the internal information to support OEvent, it is not recommended to interfere with this object except for querying it during testing.

obj.oevent_listeners.onSomething array

Each event will have its own array (keyed against the event name) that contains the listeners for that event.

Event shortcut method

Each event will provide a shortcut method that allows you to easily and quickly add callbacks and trigger the event. The return type of this event is the source object itself which allows for chained event coding.

The shortcut method has two overloads:

obj.onSomething( function )

Passing a single function to the method adds that function as a listener.

obj.onSomething(function(){ alert('Event fired') }); // adds a callback to the event

obj.onSomething()

Passing anything other than a single function argument will cause the event to be fired with the specified arguments.

obj.onSomething(); // fires the event with no arguments
obj.onSomething(123); // fires the event passing '123' as the first argument

Chaining with events

obj.onLoad(function(){ alert("LOAD!"); }).onReady(function(){ alert("READY!") }).go();

Explicitly firing events - obj.fire_onSomething

Each event also gets a fire_* method which triggers the event. This is useful for when you want to fire an event with a single function argument (which would be interpreted as a listenFor by the shortcut method).

Explicitly listening for events - obj.listenFor_onSomething

Each event also gets a listenFor_* method which adds the specified function to the listener list. This is the same as:

var func = function(){};
obj.onSomething( func );

Removing callbacks

If you want to remove a callback from the array you can use the simple forget method which can be accessed directly off the event shortcut method.

Usage: obj.eventShortcutMethod.forget( [ callback | index ] )

So callbacks registered on an event called onSomething can be removed by calling:

obj.onSomething.forget( callback )

If you want to forget all callbacks, you can call the forget method without any arguments:

obj.onSomething.forget();

If you want to forget a callback by index, just pass the index:

obj.onSomething.forget( index );

Events in classes

• See OClass plugin for details on how to use events in a true object-oriented way

Tutorials

• see Writing OO Code using Objx