JSignal 0.2

JSignal is a loose port of the signal system implemented by GTKs GLib. JSignal project uses signals and handlers to allow for the registration of callback functions to events.
To use JSignal those classes which will emit signals (cause events) must register the signals that each class will emit. Note that if a class extends another class (has a superclass) it will inherit any signals registered by the parent class and can emit those signals as well. In addition a new global-type of signal can be registered which is class non-specific. Any class can emit a global signal.
After you have a class with registered signals you can begin connecting callback functions to those signals. Callback functions are connected (registered to listen for) to signals by specifying the signal and the object instance that will emit that signal; this registration results in the creation of a handler.
Multiple handlers can be configured for the same signal on the same object instance. In addition to instance-specific signal handlers a handler can also be registered to execute when a global signal (created using j_signal_new_global) is emitted; again, regardless of emitting instance. Note that when a global signal is emitted by an instance those handlers that are registered globally (using j_signal_handler_connect_global) will be executed BEFORE any instance-specific handlers.
To emit a signal - thus causing an event - the class which registered the signal should use the j_signal_emit function and pass any additional information to the callback function via the event detail argument. This detail object should be an array of name => value pairs.
Illustrative examples are provided below.
Note: In order for signal inheritance to work properly it is recommended that a classs prototype be given a parent member which points to the constructor of the classs superclass.
Main features:
- Multiple Handlers per Event
Multiple callback functions can be registered per signal per object instance.
- Signal Inheritance
The signals registered by an objects superclass are inherited by any extending child classes.
- Ordered Handler Execution
Like the DOM event handling system all handlers set to fire in response to a particular event fire in the order they were registered.
- Chained Handler Execution
Also like the DOM event handling model, when a handler returns a value of false any subsequent handlers will NOT be executed.
- Temporary Handler Blocking
Handlers can have blocks placed against them cumulatively; allowing for the selectively temporary disabling of handlers.
- Global Signals
Signals (as used in GLib) are class-specific. A signal registered under the class type of Integer can only be emitted by Integer instances. A global signal (registered using j_signal_new_global) can be emitted by any and all instances regardless of their class. This is essentially equivelant to registering a signal using the Javascript Object class type.
- Global Handlers
As signals are traditionally class specific it follows that handlers are instance specific. However global signals can be handled by both instance-specific handlers AND global handlers. A global handler is executed whenever a global signal is emitted, regardless of the emitting instance and its class type. Note that global handlers are executed BEFORE instance-specific handlers.