The ModuleLoader class triggers several events, including setup, ready, loading, unload, progress, error, and urlChanged. You can use these events to track the progress of the loading process, and find out when a module has been unloaded or when the ModuleLoader target URL has changed.

The following example uses a custom ModuleLoader component. This component reports all the events of the modules as they are loaded by the main application.

Custom ModuleLoader:

<?xml version="1.0" encoding="iso-8859-1"?>
<!-- modules/CustomModuleLoader.mxml -->
<mx:ModuleLoader xmlns:mx="http://www.adobe.com/2006/mxml" xmlns="*" creationComplete="init()">
  <mx:Script>
    <![CDATA[
    public function init():void {
        addEventListener("urlChanged", onUrlChanged);
        addEventListener("loading", onLoading);
        addEventListener("progress", onProgress);
        addEventListener("setup", onSetup);
        addEventListener("ready", onReady);
        addEventListener("error", onError);
        addEventListener("unload", onUnload);

        standin = panel;
        removeChild(standin);        
    }
    
    public function onUrlChanged(event:Event):void {
        if (url == null) {
            if (contains(standin))
                removeChild(standin);
        } else {
            if (!contains(standin))
                addChild(standin);
        }
        progress.indeterminate=true;
        unload.enabled=false;
        reload.enabled=false;
    }

    public function onLoading(event:Event):void {
        progress.label="Loading module " + url;
        if (!contains(standin))
            addChild(standin);

        progress.indeterminate=true;
        unload.enabled=false;
        reload.enabled=false;
    }
    
    public function onProgress(event:Event):void {
        progress.label="Loaded %1 of %2 bytes...";
        progress.indeterminate=false;
        unload.enabled=true;
        reload.enabled=false;
    }
    
    public function onSetup(event:Event):void {
        progress.label="Module " + url + " initialized!";
        progress.indeterminate=false;
        unload.enabled=true;
        reload.enabled=true;
    }
    
    public function onReady(event:Event):void {
        progress.label="Module " + url + " successfully loaded!";
        unload.enabled=true;
        reload.enabled=true;

        if (contains(standin))
            removeChild(standin);
    }
    
    public function onError(event:Event):void {
        progress.label="Error loading module " + url;
        unload.enabled=false;
        reload.enabled=true;
    }
    
    public function onUnload(event:Event):void {
        if (url == null) {
            if (contains(standin))
                removeChild(standin);
        } else {
            if (!contains(standin))
                addChild(standin);
        }
        progress.indeterminate=true;
        progress.label="Module " + url + " was unloaded!";
        unload.enabled=false;
        reload.enabled=true;
    }
    
    public var standin:DisplayObject;
    ]]>
  </mx:Script>

  <mx:Panel id="panel" width="100%">
    <mx:ProgressBar width="100%" id="progress" source="{this}"/>
    <mx:HBox width="100%">
      <mx:Button id="unload" 
        label="Unload Module" 
        click="unloadModule()"
      />
      <mx:Button id="reload" 
        label="Reload Module" 
        click="unloadModule();loadModule()"
      />
    </mx:HBox>
  </mx:Panel>
</mx:ModuleLoader>

Main application:

<?xml version="1.0"?>
<!-- modules/EventApp.mxml -->
<mx:Application xmlns="*" xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
            [Bindable]
            public var selectedItem:Object;
        ]]>
    </mx:Script>
    <mx:ComboBox 
        width="215" 
        labelField="label" 
        close="selectedItem=ComboBox(event.target).selectedItem"
    >
        <mx:dataProvider>
            <mx:Object label="Select Coverage"/>        
            <mx:Object 
                label="Life Insurance" 
                module="insurancemodules/LifeInsurance.swf"
            />
            <mx:Object 
                label="Auto Insurance" 
                module="insurancemodules/AutoInsurance.swf"
            />          
            <mx:Object 
                label="Home Insurance" 
                module="insurancemodules/HomeInsurance.swf"
            />
        </mx:dataProvider>
    </mx:ComboBox>

    <mx:Panel width="100%" height="100%">
        <CustomModuleLoader id="mod" 
            width="100%" 
            url="{selectedItem.module}"
        />
    </mx:Panel>
    <mx:HBox>
        <mx:Button label="Unload" click="mod.unloadModule()"/> 
        <mx:Button label="Nullify" click="mod.url = null"/>
    </mx:HBox>  
</mx:Application>
The executing SWF file for the previous example is shown below:

The insurance modules used in this example are simple forms, such as the following:

<?xml version="1.0" encoding="utf-8"?>
<!-- modules/insurancemodules/AutoInsurance.mxml -->
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" 
    layout="absolute" 
    backgroundColor="#ffffff" 
    width="100%" 
    height="100%"
>
    <mx:Label 
        x="147" 
        y="50" 
        text="Auto Insurance" 
        fontSize="28" 
        fontFamily="Myriad Pro"
    />
    <mx:Form left="47" top="136">
        <mx:FormHeading label="Coverage"/>
        <mx:FormItem label="Latte Spillage">
            <mx:TextInput id="latte" width="200" />
        </mx:FormItem>
        <mx:FormItem label="Shopping Cart to the Door">
            <mx:TextInput id="cart" width="200" />
        </mx:FormItem>
        <mx:FormItem label="Irate Moose">
            <mx:TextInput id="moose" width="200" />
        </mx:FormItem>
        <mx:FormItem label="Color Fade">
            <mx:ColorPicker />
        </mx:FormItem>
    </mx:Form>
</mx:Module>

Using the error event

The error event gives you an opportunity to gracefully fail when a module does not load for some reason. In the following example, you can load and unload a module by using the Button controls. To trigger an error event, change the URL in the TextInput control to a module that does not exist. The error handler displays a message to the user and writes the error message to the trace log.

<?xml version="1.0"?>
<!-- modules/ErrorEventHandler.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
        import mx.events.ModuleEvent;
        import mx.modules.*;
        import mx.controls.Alert;
        
        private function errorHandler(e:ModuleEvent):void {
            Alert.show("There was an error loading the module." + 
                " Please contact the Help Desk.");
            trace(e.errorText);
        }
  
        public function createModule():void {
            if (chartModuleLoader.url == ti1.text) {
                // If they are the same, call loadModule.   
                chartModuleLoader.loadModule();
            } else {
                // If they are not the same, then change the url, 
                // which triggers a call to the loadModule() method.
                chartModuleLoader.url = "assets/" + ti1.text;
            }
        }
        
        public function removeModule():void {
            chartModuleLoader.unloadModule();
        }

        ]]>
    </mx:Script>

    <mx:Panel title="Module Example" 
        height="90%" 
        width="90%" 
        paddingTop="10" 
        paddingLeft="10" 
        paddingRight="10" 
        paddingBottom="10"
    >
        <mx:HBox>
            <mx:Label text="URL:"/>
            <mx:TextInput width="200" id="ti1" text="ColumnChartModule.swf"/>
            <mx:Button label="Load" click="createModule()"/>
            <mx:Button label="Unload" click="removeModule()"/>
        </mx:HBox>
        <mx:ModuleLoader id="chartModuleLoader" error="errorHandler(event)"/>
    </mx:Panel>
</mx:Application>
The executing SWF file for the previous example is shown below:

Using the progress event

You can use the progress event to track the progress of a module as it loads. When you add a listener for the progress event, Flex calls that listener at regular intervals during the module's loading process. Each time the listener is called, you can look at the bytesLoaded property of the event. You can compare this to the bytesTotal property to get a percentage of completion.

The following example reports the level of completion during the module's loading process. It also produces a simple progress bar that shows users how close the loading is to being complete.

<?xml version="1.0"?>
<!-- modules/SimpleProgressEventHandler.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[
        import mx.events.ModuleEvent;
        import flash.events.ProgressEvent;
        import mx.modules.*;
        
        [Bindable]
        public var progBar:String = "";
        [Bindable]
        public var progMessage:String = "";
        
        private function progressEventHandler(e:ProgressEvent):void {
            progBar += ".";
            progMessage = 
                "Module " +  
                Math.round((e.bytesLoaded/e.bytesTotal) * 100) + 
                "% loaded";
        }

        public function createModule():void {
            chartModuleLoader.loadModule();
        }
        
        public function removeModule():void {
            chartModuleLoader.unloadModule();
            progBar = "";
            progMessage = "";
        }
        ]]>
    </mx:Script>

    <mx:Panel title="Module Example" 
        height="90%" 
        width="90%" 
        paddingTop="10" 
        paddingLeft="10" 
        paddingRight="10" 
        paddingBottom="10"
    >        
        <mx:HBox>
            <mx:Label id="l2" text="{progMessage}"/>
            <mx:Label id="l1" text="{progBar}"/>
        </mx:HBox>  

        <mx:Button label="Load" click="createModule()"/>
        <mx:Button label="Unload" click="removeModule()"/>

        <mx:ModuleLoader 
            id="chartModuleLoader" 
            url="ColumnChartModule.swf" 
            progress="progressEventHandler(event)"
        />
    </mx:Panel>    
</mx:Application>
The executing SWF file for the previous example is shown below:

You can also connect a module loader to a ProgressBar control. The following example creates a custom component for the ModuleLoader that includes a ProgressBar control. The ProgressBar control displays the progress of the module loading.

<?xml version="1.0"?>
<!-- modules/MySimpleModuleLoader.mxml -->
<mx:ModuleLoader xmlns:mx="http://www.adobe.com/2006/mxml">
    <mx:Script>
        <![CDATA[        
            private function clickHandler():void {
                if (!url) { 
                    url="ColumnChartModule.swf"; 
                } 
                loadModule();
            }        
        ]]>
    </mx:Script>

    <mx:ProgressBar 
        id="progress" 
        width="100%" 
        source="{this}"
    />
    <mx:HBox width="100%">
      <mx:Button 
        id="load" 
        label="Load" 
        click="clickHandler()"
      />
      <mx:Button 
        id="unload" 
        label="Unload" 
        click="unloadModule()"
      />
      <mx:Button 
        id="reload" 
        label="Reload" 
        click="unloadModule();loadModule();"
      />
    </mx:HBox>
</mx:ModuleLoader>

You can use this module in a simple application, as the following example shows:

<?xml version="1.0"?>
<!-- modules/ComplexProgressEventHandler.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" xmlns:local="*">

    <mx:Panel title="Module Example" 
        height="90%" 
        width="90%" 
        paddingTop="10" 
        paddingLeft="10" 
        paddingRight="10" 
        paddingBottom="10"
    >        
        <mx:Label text="Use the buttons below to load and unload    
            the module."/>
        <local:MySimpleModuleLoader id="customLoader"/>
    </mx:Panel>
    
</mx:Application>
The executing SWF file for the previous example is shown below:

This example does not change the ProgressBar label property for all events. For example, if you load and then unload the module, the label property remains at "LOADING 100%". To adjust the label properly, you must define other event handlers for the ModuleLoader events, such as unload and error.