Using ModuleLoader events -- Flex 2.01

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's target URL has changed.

Subtopics

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 = 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>

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>

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>

This example does not change the ProgressBar's 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.