Signals & Receivers

Generality

The "signal engine" include in the package system.signals is a very simple messaging tools.

With a Signal class we can define objects who communicates by signals and can be use to create a light-weight implementation of the Observer pattern.

A signal emit simple values with its own array of receivers (slots). This values can be strongly-typed with an internal checking process.

Receivers (or Slots) can be defines with a simple Function reference or a custom object who implements the system.signals.Receiver interface.

Receivers subscribe to real objects, not to string-based channels. Event string constants are no longer needed like W3C DOM 2/3 event model. Interfaces.

Hello World

We begin with a first basic example.

In this example we use the system.signals.Signal.

function write( message:String ):void
{
    console.log( message ) ;
}

var signal =  new Signal() ;

signal.connect( write ) ;

signal.emit( "hello world" ) ; // hello world
signal.emit( "thank you" ) ; // thank you

Features

Signals have many features.

Disconnect a specific receiver or all receiver

You can disconnect the receivers registered in a Signaler object with the method disconnect(). This method can target a specific receiver (function reference or Receiver instance) but you can disconnect all registered receivers if you don't passed-in value.

Example :

var signal = new Signal() ;

signal.connect( slot1 ) ;
signal.connect( slot2 ) ;
signal.connect( slot3 ) ;

trace( signal.length ) ; // 3

signal.disconnect( slot2 ) ;

trace( signal.length ) ; // 2

signal.disconnect() ; // disconnect all

trace( signal.length ) ; // 0

Auto disconnect feature

Receivers can be added for a one-time call and removed automatically on dispatch.

var receiver = function( message )
{
    console.log( message ) ;
}

var signal = new Signal() ;

signal.connect( receiver , 0 , true ) ;

signal.emit( "hello world" ) ;  // hello world
signal.emit( "bonjour monde" ) ;

Only the first message is dispatched, the reveiver is automatically disconnected and can't receive the next messages.

Receiver priority

When you connect a receiver with the connect method you can apply a priority over your reference.

The priority is designated by an int value ( an integer > 0 ). The higher the number, the higher the priority. All receivers with priority n are processed before receivers of priority n-1. If two or more receivers share the same priority, they are processed in the order in which they were added. The default priority is 0.

var slot1 = function( message )
{
    console.log( "slot1: " + message ) ;
}

var slot2 = function( message )
{
    console.log( "slot2: " + message ) ;
}

var slot3 = function( message )
{
    console.log( "slot3: " + message ) ;
}

var signal = new Signal() ;

signal.connect( slot1 ,  10 ) ;
signal.connect( slot2 , 999 ) ;
signal.connect( slot3 , 400 ) ;

signal.emit( "hello world" ) ;

// slot2: hello world
// slot3: hello world
// slot1: hello world

Other features

• You can retrieve the number of receivers with the read-only attribute : signal.length
• You can retrieve if the signal contains one or more receivers with the method : signal.connected()
• You can retrieve if a specific receiver is connected with the method : signal.hasReceiver( receiver )