ProgressBar control

The ProgressBar control is part of the MX component set. There is no Spark equivalent.

The ProgressBar control provides a visual representation of the progress of a task over time. There are two types of ProgressBar controls: determinate and indeterminate. A determinate ProgressBar control is a linear representation of the progress of a task over time. You can use this when the user is required to wait for an extended period of time, and the scope of the task is known.

An indeterminate ProgressBar control represents time-based processes for which the scope is not yet known. As soon as you can determine the scope, you should use a determinate ProgressBar control.

The following example shows both types of ProgressBar controls:

Top.
Determinate ProgressBar control

Bottom.
Indeterminate ProgressBar control

Use the ProgressBar control when the user is required to wait for completion of a process over an extended period of time. You can attach the ProgressBar control to any kind of loading content. A label can display the extent of loaded contents when enabled.

ProgressBar control modes

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.

Creating a ProgressBar control

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.

Defining the label of a 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.