How to use the ProgressBar component (Starling version)

The ProgressBar class displays a visual indicator of how much of a task has been completed. It may fill up horizontally or vertically.

Screenshot of a Feathers ProgressBar component
ProgressBar components skinned with MetalWorksMobileTheme

The Basics

First, let's create a ProgressBar control, set up its range of values, and add it to the display list.

var progress:ProgressBar = new ProgressBar();
progress.minimum = 0;
progress.maximum = 100;
progress.value = 10;
this.addChild( progress );

The minimum and maximum properties set the range of the progress bar. The value property must be a value between the minimum and maximum.

By default, the progress bar direction is horizontal. You can change the direction property to make the progress bar vertically-oriented instead.

progress.direction = Direction.VERTICAL;

Skinning a ProgressBar

A progress bar provides a number of properties that can be used to customize its appearance. For full details about what skin and style properties are available, see the ProgressBar API reference. We'll look at a few of the most common ways of styling a progress bar below.

Background and fill skins

The backgroundSkin and fillSkin properties are used to customize the appearance of the progress bar.

var backgroundSkin:Image = new Image( backgroundTexture );
backgroundSkin.width = 150;
progress.backgroundSkin = backgroundSkin;
 
var fillSkin:Image = new Image( fillTexture );
fillSkin.width = 20;
progress.fillSkin = fillSkin;

Notice that we're setting width values on the skins before passing them in. For the background, we're doing this so that the initial width of the progress bar is at least 150 pixels wide. We can still set the width property on the progress bar directly to a smaller or a larger value, if we'd prefer. However, if we don't set the progress bar's width explicitly, the progress bar knows to automatically calculate it's dimensions from the size of the background skin.

For the fill skin, we want to ensure that the fill is never smaller than 20 pixels. Perhaps the fill is a rounded rectangle, so the edges need to be at least 10 pixels wide before they start to overlap or distort. We want to avoid that, so we set the width of the fillSkin to inform the progress bar that this is the width that corresponds to the value of the minimum property. In other words, if the value property is equal to the minimum property (in this case, if they are 0), then the fill skin will be 20 pixels wide. As the value property increases toward 100, the fill skin's width will increase up to 150 pixels.

Additionally, two other skin properties, backgroundDisabledSkin and fillDisabledSkin, may be used to give a progress bar a different appearance when it is disabled. These skins are optional. For instance, if the backgroundDisabledSkin is not provided, the regular backgroundSkin will be used when isEnabled is false.

Layout

Like many components, the progress bar has padding values. These can be used to add space between the edge of the background and the edge of the fill. For instance, you might want to display part of the background as a border around the fill.

progress.paddingTop = 2;
progress.paddingRight = 3;
progress.paddingBottom = 2;
progress.paddingLeft = 3;

If all four padding values should be the same, you may use the padding property to quickly set them all at once:

progress.padding = 20;