fromErrorEvent

Creates an Observable sequence from the error event values of an IEventDispatcher.

static function fromErrorEvent(dispatcher : IEventDispatcher, eventName : String, 
    useCapture : Boolean = false, priority : int = 0, errorMap : Function = null) : IObservable.<*>

The useCapture and priority arguments will be used when adding an event listener to dispatcher.

If supplied, errorMap has the signature: function (event : Event) : Error

Remarks

The event listener will be added when a subscription starts and removed if the subscription is cancelled.

fromErrorEvent is usually merged with another sequence that provides success values. For example urlLoader merges events (like IOErrorEvent) using fromErrorEvent with successful values triggered by Event.COMPLETE.

If errorMap if supplied, it will be used to map Event values to Error values before being thrown. Otherwise, the default error map will be used, which supports mapping ErrorEvent, IOErrorEvent and SecurityErrorEvent to Error, IOError and SecurityError, respectively.

The returned sequence does not complete

The returned sequence errors when the event is dispatched.

Marble Diagrams

event source  ────o
                  │
output        ────x/

Return Value

IObservable.<*>

Examples

/*
 * NOTE: Observable.urlLoader should be used to load content (rather than this example)
 * as it supports cancellation, multiple error types and throttling concurrent requests
 */

var loader : URLLoader = new URLLoader();

var errors : IObservable = Observable.fromErrorEvent(loader, IOError.IO_ERROR);

var success : IObservable = Observable.fromEvent(loader, Error.COMPLETE)
    .take(1) // We should complete after the first success event
    .map(function(ev:Event) : Object { return loader.data; });

var dataOrError : IObservable = success.merge(errors);

dataOrError.subscribe(
    function(data : Object) : void { trace("Data successfully loaded"); },
    null,
    function(error : Error) : void { trace("An error occurred: " + error.message); }
    );

// Out will either be:
// Data successfully loaded (if successful)
// or
// An error occurred: <error message> (if unsuccessful)