ProgressBar control

You use the mode property to specify the operating mode of the ProgressBar control. The ProgressBar control supports the following modes of operation:

event

Use the source property to specify a loading process that emits progress and complete events. For example, the SWFLoader and Image controls emit these events as part of loading a file. You typically use a determinate ProgressBar in this mode. The ProgressBar control only updates if the value of the source property extends the EventDispatcher class. This is the default mode.

You also use this mode if you want to measure progress on multiple loads; for example, if you reload an image, or use the SWFLoader and Image controls to load multiple images.

polled

Use the source property to specify a loading process that exposes the bytesLoaded and bytesTotal properties. For example, the SWFLoader and Image controls expose these properties. You typically use a determinate ProgressBar in this mode.

manual

Set the maximum, minimum, and indeterminate properties along with calls to the setProgress() method. You typically use an indeterminate ProgressBar in this mode.

You use the <mx:ProgressBar> tag to define a ProgressBar control in MXML, as the following example shows. Specify an id value if you intend to refer to a component elsewhere in your MXML, either in another tag or in an ActionScript block.

The following example uses the default event mode to track the progress of loading an image by using the Image control:

<?xml version="1.0"?>
<!-- controls\pbar\PBarSimple.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">


    <fx:Script>
        <![CDATA[
            public function initImage():void {
              image1.load('../assets/DSC00034.JPG');
            }
        ]]>
    </fx:Script>

    <mx:VBox id="vbox0" 
        width="600" height="600">
        <mx:Canvas>
            <mx:ProgressBar width="200" source="image1"/>
        </mx:Canvas>
        <s:Button id="myButton" 
            label="Show" 
            click="initImage();"/>
        <mx:Image id="image1" 
            height="500" width="600" 
            autoLoad="false" 
            visible="true"/> 
    </mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:

After you run this example the first time, the large image will typically be stored in your browser’s cache. Before running this example a second time, clear your browser’s cache so that you can see the ProgressBar control complete. If you do not clear your browser’s cache, Flash Player loads the image from the cache and the ProgressBar control might go from 0% to 100% too quickly to see it tracking any progress in between.

In this mode, the Image control issues progress events during the load, and a complete event when the load completes.

The <mx:Image> tag exposes the bytesLoaded and bytesTotal properties, so you could also use polled mode, as the following example shows:

<mx:ProgressBar width="200" source="image1" mode="polled"/>

In manual mode, mode="manual", you use an indeterminate ProgressBar control with the maximum and minimum properties and the setProgress() method. The setProgress() method has the following method signature:

setProgress(Number completed, Number total)

completed

Specifies the progress made in the task, and must be between the maximum and minimum values. For example, if you were tracking the number of bytes to load, this would be the number of bytes already loaded.

total

Specifies the total task. For example, if you were tracking bytes loaded, this would be the total number of bytes to load. Typically, this is the same value as maximum.

To measure progress, you make explicit calls to the setProgress() method to update the ProgressBar control.

To measure progress, you make explicit calls to the setProgress() method to update the ProgressBar control.

By default, the ProgressBar displays the label LOADING xx%, where xx is the percent of the image loaded. You use the label property to specify a different text string to display.

The label property lets you include the following special characters in the label text string:

%1

Corresponds to the current number of bytes loaded.

%2

Corresponds to the total number of bytes.

%3

Corresponds to the percent loaded.

%%

Corresponds to the % sign.

For example, to define a label that displays as:

Loading Image 1500 out of 78000 bytes, 2%

use the following code:

<?xml version="1.0"?>
<!-- controls\pbar\PBarLabel.mxml -->
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark" 
    xmlns:mx="library://ns.adobe.com/flex/mx">


    <fx:Script>
        <![CDATA[
            public function initImage():void {
              image1.load('../assets/DSC00034.JPG');
            }
        ]]>
    </fx:Script>

    <mx:VBox id="vbox0" 
        width="600" height="600">
        <mx:Canvas>
            <mx:ProgressBar 
                width="300" 
                source="image1" 
                mode="polled" 
                label="Loading Image %1 out of %2 bytes, %3%%" 
                labelWidth="400"
            />        
        </mx:Canvas>
        <s:Button id="myButton" 
            label="Show" 
            click="initImage();"
        />
        <mx:Image id="image1" 
            height="500" width="600" 
            autoLoad="false" 
            visible="true"
        /> 
    </mx:VBox>
</s:Application>
The executing SWF file for the previous example is shown below:

As with the previous example, be sure to clear your browser’s cache before running this example a second time.