Selective dispatching

Selective dispatching attempts to provide a way to listen for specific dispatches.

An example why this could potentially be useful. Listening for specific keyboard events currently requires work on the listener's part:

    stage.keyDown.add(function(event:KeyboardEvent):void {
        if(event.keyCode == 65) {
            _handleArmoryPanel(event);
        }
    });

Not only does this place a burden on the users of your signal and decrease readability, it also executes these listeners regardless of whether they're actually doing anything useful.

The implementation in this pull-request introduces a new API to listen selectively for dispatches. Any ISelectiveSignal exposes four additional methods: addFor(), addOnceFor(), addWithPriorityFor() and addOnceWithPriorityFor(). So our keyboard-example above effectively becomes:

    sprite.keyDown.addFor(65, _handleArmoryPanel);

This will result in insertion of an ISelectiveSlot in the slot-list with selectivity-value 65. However what if you're not interested in the keyCode but in, say, the charCode, or perhaps you're not using KeyboardEvents at all. That's where the provider comes in. Each ISelectiveSignal requires a provider to be assigned, which generates the selectivity-value based on the dispatched data. This generated value is compared with each ISelectiveSlot's value to determine whether the slot should be executed or skipped.

Full example:

    // The provider given (3rd parameter) returns the keyCode as selectivity-value
    keyDown = new SelectiveNativeRelaySignal(sprite, KeyboardEvent.KEY_DOWN, function(e:KeyboardEvent):uint {
        return e.keyCode;
    }, KeyboardEvent);

    // Listen selectively for the 'A'-key
    keyDown.addFor(65, _handleArmoryPanel);

    // Listen selectively for the 'Q'-key
    keyDown.addFor(81, _handleQuestsPanel);

Performance-wise this holds up fabulously well against MassDispatchPerformance and even outperforms it in most cases. Your mileage may vary - especially dependent on how many listeners are listening selectively versus regularly -  however a large amount of selective listeners is bound to increase performance as it simply skips over the slots that are not interested. Selective dispatching will cost one additional function-call at max per dispatch to the provider, however it also means that it might skip another hundred slots that would have potentially been uselessly executed.

I am aware that this introduces a bunch of complexities but thought I'd give it a shot. Looking forward to suggestions!