Apache Flex 4.16.1 API Reference | All Packages | All Classes | Index | Frames No Frames |
DownloadProgressBar

Package | mx.preloaders
Class | public class DownloadProgressBar
Inheritance | DownloadProgressBar 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

| Property | Defined 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

| Property | Defined 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

| Method | Defined By
--- | --- | ---
|  | DownloadProgressBar() 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

| Method | Defined 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
|  | createChildren():void 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
|  | rslCompleteHandler(event:RSLEvent):void Event listener for the RSLEvent.RSL_COMPLETE event. | DownloadProgressBar
|  | rslErrorHandler(event:RSLEvent):void Event listener for the RSLEvent.RSL_ERROR event. | DownloadProgressBar
|  | rslProgressHandler(event:RSLEvent):void 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

backgroundAlpha | property

`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`

backgroundColor | property |

`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`

backgroundImage | property |

`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`

backgroundSize | property |

`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`

barFrameRect | property |

`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`

barRect | property |

`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`

borderRect | property |

`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_PERCENTAGE | property |

`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`.

downloadingLabel | property |

`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`

initializingLabel | property |

`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`

initProgressTotal | property |

`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`.

label | property |

`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`

labelFormat | property |

`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`

labelRect | property |

`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_TIME | property |

`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`.

percentFormat | property |

`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`

percentRect | property |

`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`

preloader | property |

`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`

showLabel | property |

`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`

showPercentage | property |

`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`

stageHeight | property |

`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`

stageWidth | property |

`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`

visible | property |

`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.

Wed Nov 15 2017, 09:50 AM +01:00