Flex 2 Developer's Guide > Building User Interfaces for Flex Applications > Using Controls > ProgressBar control

ProgressBar control

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:

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.

The ProgressBar control has the following default properties:

Subtopics

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. 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 getBytesLoaded() and getsBytesTotal() methods. For example, the SWFLoader and Image controls expose these methods. 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 using the Image control:

<?xml version="1.0"?>
<!-- controls\pbar\PBarSimple.mxml -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

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

    <mx:VBox id="vbox0" 
        width="600" height="600">
        <mx:Canvas>
            <mx:ProgressBar width="200" source="image1"/>
        </mx:Canvas>
        <mx:Button id="myButton" 
            label="Show" 
            click="initImage();"/>
        <mx:Image id="image1" 
            height="600" width="600" 
            autoLoad="false" 
            visible="true"/> 
    </mx:VBox>
</mx:Application>

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 getBytesLoaded() and getBytesTotal() methods, 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.

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 -->
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            public function initImage():void {
              image1.load('http://localhost:8100/flex/assets/DSC00034.JPG');
            }
        ]]>
    </mx: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>
        <mx:Button id="myButton" 
            label="Show" 
            click="initImage();"/>
        <mx:Image id="image1" 
            height="600" width="600" 
            autoLoad="false" 
            visible="true"/> 
    </mx:VBox>
</mx:Application>

Flex 2.01