Eventable - a MixIn class providing events and handlers/listeners
No freakin' copyright, no stinkin' license, no guarantees or warrantees
(implied, explicit or whatever). Usage is totally and completely at your own risk.
Please keep this comment block as is when modifying the code. Thanks in advance,
Ruurd Idenburg
Package: eventable.cls
Classes
|
PUBLIC
eventable
|
| Description: |
The eventable class is a mixin class, that can be used in the inheriting class to define events (by name) and trigger those events so that other classes may act upon those events. Events are defined as indexes in an events directory. The events directory is created in the events instance init method and is therefore available after the inheriting class instance creation has called it's super class init method, so the logical thing to do is to define the class instance events in the inheriting class init method for new instances. However events can also be defined later on by the inheriting class instance methods. Event handlers/listeners need to define an instance method with the name of the defined event. That method will be invoked by the triggering of the event. The handler/listener method should return the boolean .true or .false depending on whether possible other handlers/listeners should be given the opportunity to act on the event. Returning .false will allow other handlers/listeners to be invoked as well, returning .true will stop invoking other handlers/listeners. Handlers/Listeners are kept as members of an array that is the item in the directory entry for the index that has the name of the event.
|
| Attributes: |
events
(GET)
events
(SET)
|
| Methods: |
addEventHandler
addEventListener
eventHandlers
eventListeners
eventNames
removeEventHandler
removeEventListener
triggerEvent
|
Source: eventable.cls
PUBLIC
Class: eventable
Mixinclass: object
Metaclass: Class
Init
| init
|
| Expose: |
events
|
| use strict arg: |
eventArray=(.array~new)
|
| Description: |
The init method creates the directory that will have the event names as indexes and the array of handlers/listeners as items.
param eventArray=(.array~new) - optional, an array of event names provided by the inheriting class If an array with event names is provided, the entries are created in the events directory with empty arrays as items to hold future handlers/listeners.
|
Methods Summary
|
PUBLIC
addEventHandler
|
|
PUBLIC
addEventListener
|
|
PUBLIC
eventHandlers
|
|
PUBLIC
eventListeners
CLASS
|
|
PUBLIC
eventNames
|
|
PUBLIC
removeEventHandler
|
|
PUBLIC
removeEventListener
|
|
PUBLIC
triggerEvent
|
Attributes
| Attribute: |
PUBLIC
events
GET
|
| Description: |
The events attribute is a directory, whose entries can only be set privately by the inheriting class instance methods. The directory is created in the init instance method of this (the events) class.
|
| Attribute: |
PRIVATE
events
SET
|
Methods
| Method: |
addEventHandler
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
No
|
| use strict arg: |
event,
handler
|
| Description: |
addEventHander is a synonym for addEventListener
see #addEventListener
|
| Method: |
addEventListener
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
No
|
| Expose: |
events
|
| use strict arg: |
event,
listener
|
| Description: |
Adds an object to the group of interested parties
param event - the name of an event
param listener - the object interested in that event If the array of handlers/listeners does not exist yet for the event it will be created. The handler/listener object is appended to the existing or new array It is not verified if the event is a valid event for the object, the result for that condition will be that the handler/listener will never be invoked. The same handler/listener can be added multiple times, if for some reason that would be necessary for proper functioning and provided some earlier handler/listener did not return .true.
|
| Method: |
eventHandlers
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
Yes
|
| use strict arg: |
event
|
| Description: |
eventHandlers is a synonym for eventListeners
see #eventListeners
|
| Method: |
eventListeners
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
Yes
|
| Option(s): |
CLASS
|
| Expose: |
events
|
| use strict arg: |
event
|
| Description: |
Returns an array of handlers/listeners for an event.
param event - the name of an event
return anArray - an array of handlers/listeners for an event The returned array can be empty if there are no listeners for the event or if the event is unknown.
|
| Method: |
eventNames
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
Yes
|
| Description: |
Returns the list of defined events for the object
return anArray - an array of event names for the object The array can be empty if no events have been defined
|
| Method: |
removeEventHandler
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
No
|
| use strict arg: |
event,
handler
|
| Description: |
removeEventHandler is a synonym for removeEventListener
see #removeEventListener
|
| Method: |
removeEventListener
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
No
|
| Expose: |
events
|
| use strict arg: |
event,
listener
|
| Description: |
Removes a party from the group interested in an event
param event - the name of an event
param listener - the handler/listener object to be removed If the event is not known, the object can not be removed obviously
If the listener is not a member of the interested handlers/listeners, nothing can be removed.
The handlers/listeners will be regenerated to prevent sparseness.
|
| Method: |
triggerEvent
|
| Accessmodifier: |
PUBLIC
|
| Returns Value: |
Yes
|
| Expose: |
events
|
| use strict arg: |
event,
args=(.array~new)
|
| Description: |
Invokes the event handling method in the handlers/listeners for an event while successive handlers/listeners return .false, and stops to invoke following handlers/listeners on the first .true return.
@expose events - the directory of triggerable events for the class
param event - the name of the event to be handled
param args=(.array~new) - optional arguments for the handler method
|
Eventable MixIn class
Author: Ruurd J. Idenburg
The eventable class is a mixin class, that can be used in the inheriting class to define events (by name) and trigger those events so that other classes may act upon those events.
Events are defined as indexes in an events directory. The events directory is created in the events instance init method and is therefore available after the inheriting class instance creation has called it's super class init method, so the logical thing to do is to define the class instance events in the inheriting class init method for new instances. However events can also be defined later on by the inheriting class instance methods.
Event handlers/listeners need to define an instance method with the name of the defined event. That method will be invoked by the triggering of the event. The handler/listener method should return the boolean .true or .false depending on whether possible other handlers/listeners should be given the opportunity to act on the event. Returning .false will allow other handlers/listeners to be invoked as well, returning .true will stop invoking other handlers/listeners.
Handlers/Listeners are kept as members of an array that is the item in the directory entry for the index that has the name of the event.