Revision as of 00:45, 27 February 2008

(Draft)

One of the strongest aspects of the V3 core and API is that it will be strongly event driven. The main motivation for it is the fact that V3 is also plugin based, and the best way to create less dependency is by providing a large set of events that can easily manipulate the behavior of the components.

Common Events

There are some common patterns that can helps us identifying potential events to be implemented:

• Interface behavior: whenever an important UI interaction is to be taken, an event should be fired before and after it.
• Data manipulation: whenever data is to be handled, an event should be called, making it possible to manipulate the data before committing its usage.

Naming Conventions

Event names should reflect the following conventions:

• it must not start with "on".
• it must be lowercased.
• it must be an action (verb) in the present tense, like "click", "open", etc.
• composed names must still be fully lowercased, like "clicktop".
• in the normal form, it is related to an event "before" it happens. For example, the "close" event in a dialog is fired when it is to be closed, so it could be canceled and no close action is taken.
• the "after" prefix can be used for events fired after an action is taken. For example, in a dialog, the "afterClose" event could be fired after the dialog has been effectively closed. It would not be cancelable in that case.

Event Data

Event listeners will receive one and only parameter, the "Event" object. This object contains the following properties:

• name: the event name.
• sender: the object which is publishing the event.
• editor: the editor instance that holds the sender. May be the same as sender. May be null if the sender is not part of an editor instance, like a component running in standalone mode.
• data: any kind of additional data. Its format and usage is event dependent.
• listenerData: any extra data appended during the listener registration.

Methods:

• stop(): indicates that no further listeners are to be called.
• cancel(): indicates that the event is to be cancelled (if cancelable).

Listener Calling Scope

By default, listener function will be called under the scope (the "this" reference) of the event publisher.

When registering listeners, it is possible to assign a specific object to used as the scope in the listener

Order and Priority

When registering an event listener, it is possible to set its priority inside the listeners queue. The priority is simply a numeric value. By default, listeners have priority level 10. Lower priority values are executed first.

Listeners that share the same priority level are executed in the registration order, so those registered first are called first.

Event Related Functions

Event Listener Registration

subscription = <object>.addListener( eventName, listenerFunction [,scopeObj] [,listenerData] [,priority] )

• eventName: the event being listed.
• listenerFunction: the function to be called on event.
• scopeObj: (optional) the object to be used as the scope when calling listenerFunction. If null or not defined, "object" is the scope.
• listenerData: (optional) extra data to be passed to the listener function in the Event object.
• priority: (optional) the priority level value. If not defined, it is set to 10.
• subscription: an opaque, read only value that can be used to remove the listener.

Event Listener Removal

Event.removeListener( subscription )

subscription: the value returned by the addListener method.

Event Firing

canceled = <object>.fire( eventName [,data] )

• eventName: the event being fired.
• data: (optional) data to be passed to event listeners. It may suffer manipulation.
• canceled: a boolean indicating that a listener marked the event to be canceled.

Event Listeners Calling

listenerFunction( event )

• event: the Event object.