Packagemx.preloaders
Classpublic class DownloadProgressBar
InheritanceDownloadProgressBar Inheritance flash.display.Sprite
Implements IPreloaderDisplay

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The DownloadProgressBar class displays download progress. It is used by the Preloader control to provide user feedback while the application is downloading and loading.

The download progress bar displays information about two different phases of the application: the download phase and the initialization phase.

In the Application container, use the the preloader property to specify the name of your subclass.

You can implement a custom download progress bar component by creating a subclass of the DownloadProgressBar class. Do not implement a download progress bar as an MXML component because it loads too slowly.

See also

mx.core.Application
mx.preloaders.IPreloaderDisplay
mx.preloaders.Preloader


Public Properties
 PropertyDefined By
  backgroundAlpha : Number
Alpha level of the SWF file or image defined by the backgroundImage property, or the color defined by the backgroundColor property.
DownloadProgressBar
  backgroundColor : uint
Background color of a download progress bar.
DownloadProgressBar
  backgroundImage : Object
The background image of the application, which is passed in by the preloader.
DownloadProgressBar
  backgroundSize : String
Scales the image specified by backgroundImage to different percentage sizes.
DownloadProgressBar
  initializingLabel : String
[static] The string to display as the label while in the initializing phase.
DownloadProgressBar
  preloader : Sprite
[write-only] The Preloader class passes in a reference to itself to the display class so that it can listen for events from the preloader.
DownloadProgressBar
  stageHeight : Number
The height of the stage, which is passed in by the Preloader class.
DownloadProgressBar
  stageWidth : Number
The width of the stage, which is passed in by the Preloader class.
DownloadProgressBar
  visible : Boolean
[override] Specifies whether the download progress bar is visible.
DownloadProgressBar
Protected Properties
 PropertyDefined By
  barFrameRect : RoundedRectangle
[read-only] The dimensions of the progress bar border.
DownloadProgressBar
  barRect : RoundedRectangle
[read-only] The dimensions of the progress bar.
DownloadProgressBar
  borderRect : RoundedRectangle
[read-only] The dimensions of the border of the display.
DownloadProgressBar
  downloadingLabel : String
The string to display as the label while in the downloading phase.
DownloadProgressBar
  DOWNLOAD_PERCENTAGE : uint = 60
The percentage of the progress bar that the downloading phase fills when the SWF file is fully downloaded.
DownloadProgressBar
  initProgressTotal : uint = 6
The total number of validation events you expect to get in the initializing phase.
DownloadProgressBar
  label : String
Text to display when the progress bar is active.
DownloadProgressBar
  labelFormat : TextFormat
[read-only] The TextFormat object of the TextField component of the label.
DownloadProgressBar
  labelRect : Rectangle
[read-only] The dimensions of the TextField component for the label.
DownloadProgressBar
  MINIMUM_DISPLAY_TIME : uint = 0
The minimum number of milliseconds that the display should appear visible.
DownloadProgressBar
  percentFormat : TextFormat
[read-only] The TextFormat of the TextField component for displaying the percent.
DownloadProgressBar
  percentRect : Rectangle
[read-only] The dimensions of the TextField component for displaying the percent.
DownloadProgressBar
  showLabel : Boolean
Controls whether to display the label, true, or not, false.
DownloadProgressBar
  showPercentage : Boolean
Controls whether to display the percentage, true, or not, false.
DownloadProgressBar
Public Methods
 MethodDefined By
  
Constructor.
DownloadProgressBar
  
initialize():void
Called by the Preloader after the download progress bar has been added as a child of the Preloader.
DownloadProgressBar
Protected Methods
 MethodDefined By
  
center(width:Number, height:Number):void
Centers the download progress bar based on the passed in dimensions.
DownloadProgressBar
  
completeHandler(event:Event):void
Event listener for the Event.COMPLETE event.
DownloadProgressBar
  
Creates the subcomponents of the display.
DownloadProgressBar
  
getPercentLoaded(loaded:Number, total:Number):Number
Returns the percentage value of the application loaded.
DownloadProgressBar
  
initCompleteHandler(event:Event):void
Event listener for the FlexEvent.INIT_COMPLETE event.
DownloadProgressBar
  
initProgressHandler(event:Event):void
Event listener for the FlexEvent.INIT_PROGRESS event.
DownloadProgressBar
  
progressHandler(event:ProgressEvent):void
Event listener for the ProgressEvent.PROGRESS event.
DownloadProgressBar
  
Event listener for the RSLEvent.RSL_COMPLETE event.
DownloadProgressBar
  
Event listener for the RSLEvent.RSL_ERROR event.
DownloadProgressBar
  
Event listener for the RSLEvent.RSL_PROGRESS event.
DownloadProgressBar
  
setProgress(completed:Number, total:Number):void
Updates the display of the download progress bar with the current download information.
DownloadProgressBar
  
showDisplayForDownloading(elapsedTime:int, event:ProgressEvent):Boolean
Defines the algorithm for determining whether to show the download progress bar while in the download phase.
DownloadProgressBar
  
showDisplayForInit(elapsedTime:int, count:int):Boolean
Defines the algorithm for determining whether to show the download progress bar while in the initialization phase, assuming that the display is not currently visible.
DownloadProgressBar
Property Detail
backgroundAlphaproperty
backgroundAlpha:Number

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Alpha level of the SWF file or image defined by the backgroundImage property, or the color defined by the backgroundColor property. Valid values range from 0 to 1.0.

You can specify either a backgroundColor or a backgroundImage, but not both.

The default value is 1.0.


Implementation
    public function get backgroundAlpha():Number
    public function set backgroundAlpha(value:Number):void
backgroundColorproperty 
backgroundColor:uint

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Background color of a download progress bar. You can have either a backgroundColor or a backgroundImage, but not both.


Implementation
    public function get backgroundColor():uint
    public function set backgroundColor(value:uint):void
backgroundImageproperty 
backgroundImage:Object

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The background image of the application, which is passed in by the preloader. You can specify either a backgroundColor or a backgroundImage, but not both.

A value of null means "not set". If this style and the backgroundColor style are undefined, the component has a transparent background.

The preloader does not display embedded images. You can only use images loaded at runtime.

The default value is null.


Implementation
    public function get backgroundImage():Object
    public function set backgroundImage(value:Object):void
backgroundSizeproperty 
backgroundSize:String

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Scales the image specified by backgroundImage to different percentage sizes. A value of "100%" stretches the image to fit the entire component. To specify a percentage value, you must include the percent sign (%). A value of "auto", maintains the original size of the image.

The default value is "auto".


Implementation
    public function get backgroundSize():String
    public function set backgroundSize(value:String):void
barFrameRectproperty 
barFrameRect:RoundedRectangle  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The dimensions of the progress bar border. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get barFrameRect():RoundedRectangle
barRectproperty 
barRect:RoundedRectangle  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The dimensions of the progress bar. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get barRect():RoundedRectangle
borderRectproperty 
borderRect:RoundedRectangle  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The dimensions of the border of the display. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get borderRect():RoundedRectangle
DOWNLOAD_PERCENTAGEproperty 
protected var DOWNLOAD_PERCENTAGE:uint = 60

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The percentage of the progress bar that the downloading phase fills when the SWF file is fully downloaded. The rest of the progress bar is filled during the initializing phase. This should be a value from 0 to 100.

The default value is 60.

downloadingLabelproperty 
downloadingLabel:String

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The string to display as the label while in the downloading phase.

The default value is "Loading".


Implementation
    protected function get downloadingLabel():String
    protected function set downloadingLabel(value:String):void
initializingLabelproperty 
initializingLabel:String

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The string to display as the label while in the initializing phase.

The default value is "Initializing".


Implementation
    public static function get initializingLabel():String
    public static function set initializingLabel(value:String):void
initProgressTotalproperty 
protected var initProgressTotal:uint = 6

Language Version : ActionScript 3.0
Product Version : Flex 4
Runtime Versions : Flash Player 9, AIR 1.1

The total number of validation events you expect to get in the initializing phase. This should be an integer greater or equal to 4 (and note that if it is greater than 4 you might have an inefficiency in your initialization code)

The default value is 6.

labelproperty 
label:String

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Text to display when the progress bar is active. The Preloader class sets this value before displaying the progress bar. Implementing this property in a subclass is optional.

The default value is "".


Implementation
    protected function get label():String
    protected function set label(value:String):void
labelFormatproperty 
labelFormat:TextFormat  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The TextFormat object of the TextField component of the label. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get labelFormat():TextFormat
labelRectproperty 
labelRect:Rectangle  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The dimensions of the TextField component for the label. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get labelRect():Rectangle
MINIMUM_DISPLAY_TIMEproperty 
protected var MINIMUM_DISPLAY_TIME:uint = 0

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The minimum number of milliseconds that the display should appear visible. If the downloading and initialization of the application takes less time than this value, then Flex pauses for this amount of time before dispatching the complete event.

The default value is 0.

percentFormatproperty 
percentFormat:TextFormat  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The TextFormat of the TextField component for displaying the percent. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get percentFormat():TextFormat
percentRectproperty 
percentRect:Rectangle  [read-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The dimensions of the TextField component for displaying the percent. This is a read-only property which you must override if you need to change it.


Implementation
    protected function get percentRect():Rectangle
preloaderproperty 
preloader:Sprite  [write-only]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The Preloader class passes in a reference to itself to the display class so that it can listen for events from the preloader.


Implementation
    public function set preloader(value:Sprite):void
showLabelproperty 
showLabel:Boolean

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Controls whether to display the label, true, or not, false.

The default value is true.


Implementation
    protected function get showLabel():Boolean
    protected function set showLabel(value:Boolean):void
showPercentageproperty 
showPercentage:Boolean

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Controls whether to display the percentage, true, or not, false.

The default value is true.


Implementation
    protected function get showPercentage():Boolean
    protected function set showPercentage(value:Boolean):void
stageHeightproperty 
stageHeight:Number

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The height of the stage, which is passed in by the Preloader class.


Implementation
    public function get stageHeight():Number
    public function set stageHeight(value:Number):void
stageWidthproperty 
stageWidth:Number

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

The width of the stage, which is passed in by the Preloader class.


Implementation
    public function get stageWidth():Number
    public function set stageWidth(value:Number):void
visibleproperty 
visible:Boolean[override]

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Specifies whether the download progress bar is visible.

When the Preloader control determines that the progress bar should be displayed, it sets this value to true. When the Preloader control determines that the progress bar should be hidden, it sets the value to false.

A subclass of the DownloadProgressBar class should never modify this property. Instead, you can override the setter method to recognize when the Preloader control modifies it, and perform any necessary actions.

The default value is false.


Implementation
    public function get visible():Boolean
    public function set visible(value:Boolean):void
Constructor Detail
DownloadProgressBar()Constructor
public function DownloadProgressBar()

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Constructor.

Method Detail
center()method
protected function center(width:Number, height:Number):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Centers the download progress bar based on the passed in dimensions.

Parameters

width:Number — The width of the area in which to center the download progress bar.
 
height:Number — The height of the area in which to center the download progress bar.

completeHandler()method 
protected function completeHandler(event:Event):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the Event.COMPLETE event. The default implementation does nothing.

Parameters

event:Event — The event object.

createChildren()method 
protected function createChildren():void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Creates the subcomponents of the display.

getPercentLoaded()method 
protected function getPercentLoaded(loaded:Number, total:Number):Number

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Returns the percentage value of the application loaded.

Parameters

loaded:Number — Number of bytes of the application SWF file that have been downloaded.
 
total:Number — Size of the application SWF file in bytes.

Returns
Number — The percentage value of the loaded application.
initCompleteHandler()method 
protected function initCompleteHandler(event:Event):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the FlexEvent.INIT_COMPLETE event.

Parameters

event:Event — The event object.

initialize()method 
public function initialize():void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Called by the Preloader after the download progress bar has been added as a child of the Preloader. This should be the starting point for configuring your download progress bar.

initProgressHandler()method 
protected function initProgressHandler(event:Event):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the FlexEvent.INIT_PROGRESS event. This implementation updates the progress bar each time the event is dispatched, and changes the text of the label.

Parameters

event:Event — The event object.

progressHandler()method 
protected function progressHandler(event:ProgressEvent):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the ProgressEvent.PROGRESS event. This implementation updates the progress bar with the percentage of bytes downloaded.

Parameters

event:ProgressEvent — The event object.

rslCompleteHandler()method 
protected function rslCompleteHandler(event:RSLEvent):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the RSLEvent.RSL_COMPLETE event.

Parameters

event:RSLEvent — The event object.

rslErrorHandler()method 
protected function rslErrorHandler(event:RSLEvent):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the RSLEvent.RSL_ERROR event. This event listner handles any errors detected when downloading an RSL.

Parameters

event:RSLEvent — The event object.

rslProgressHandler()method 
protected function rslProgressHandler(event:RSLEvent):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Event listener for the RSLEvent.RSL_PROGRESS event. The default implementation does nothing.

Parameters

event:RSLEvent — The event object.

setProgress()method 
protected function setProgress(completed:Number, total:Number):void

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Updates the display of the download progress bar with the current download information. A typical implementation divides the loaded value by the total value and displays a percentage. If you do not implement this method, you should create a progress bar that displays an animation to indicate to the user that a download is occurring.

The setProgress() method is only called if the application is being downloaded from a remote server and the application is not in the browser cache.

Parameters

completed:Number — Number of bytes of the application SWF file that have been downloaded.
 
total:Number — Size of the application SWF file in bytes.

showDisplayForDownloading()method 
protected function showDisplayForDownloading(elapsedTime:int, event:ProgressEvent):Boolean

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Defines the algorithm for determining whether to show the download progress bar while in the download phase.

Parameters

elapsedTime:int — number of milliseconds that have elapsed since the start of the download phase.
 
event:ProgressEvent — The ProgressEvent object that contains the bytesLoaded and bytesTotal properties.

Returns
Boolean — If the return value is true, then show the download progress bar. The default behavior is to show the download progress bar if more than 700 milliseconds have elapsed and if Flex has downloaded less than half of the bytes of the SWF file.
showDisplayForInit()method 
protected function showDisplayForInit(elapsedTime:int, count:int):Boolean

Language Version : ActionScript 3.0
Product Version : Flex 3
Runtime Versions : Flash Player 9, AIR 1.1

Defines the algorithm for determining whether to show the download progress bar while in the initialization phase, assuming that the display is not currently visible.

Parameters

elapsedTime:int — number of milliseconds that have elapsed since the start of the download phase.
 
count:int — number of times that the initProgress event has been received from the application.

Returns
Boolean — If true, then show the download progress bar.