flash.events

# ProgressEvent - AS3

Package | flash.events
Class | public class ProgressEvent
Inheritance | ProgressEvent Event Object
Subclasses | ModuleEvent, ResourceEvent, RSLEvent, StyleEvent, VideoProgressEvent

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

A ProgressEvent object is dispatched when a load operation has begun or a socket has received data. These events are usually generated when SWF files, images or data are loaded into an application. There are two types of progress events: `ProgressEvent.PROGRESS` and `ProgressEvent.SOCKET_DATA`. Additionally, in AIR ProgressEvent objects are dispatched when a data is sent to or from a child process using the NativeProcess class.

View the examples

Related API Elements

FileStream class
LoaderInfo class
Socket class

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bubbles : Boolean [read-only] Indicates whether an event is a bubbling event. | Event
|  | bytesLoaded : Number The number of items or bytes loaded when the listener processes the event. | ProgressEvent
|  | bytesTotal : Number The total number of items or bytes that will be loaded if the loading process succeeds. | ProgressEvent
|  | cancelable : Boolean [read-only] Indicates whether the behavior associated with the event can be prevented. | Event
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | currentTarget : Object [read-only] The object that is actively processing the Event object with an event listener. | Event
|  | eventPhase : uint [read-only] The current phase in the event flow. | Event
|  | target : Object [read-only] The event target. | Event
|  | type : String [read-only] The type of event. | Event

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ProgressEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, bytesLoaded:Number = 0, bytesTotal:Number = 0) Creates an Event object that contains information about progress events. | ProgressEvent
|  | clone():Event [override] Creates a copy of the ProgressEvent object and sets each property's value to match that of the original. | ProgressEvent
|  | formatToString(className:String, ... arguments):String A utility function for implementing the toString() method in custom ActionScript 3.0 Event classes. | Event
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isDefaultPrevented():Boolean Checks whether the preventDefault() method has been called on the event. | Event
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | preventDefault():void Cancels an event's default behavior if that behavior can be canceled. | Event
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | stopImmediatePropagation():void Prevents processing of any event listeners in the current node and any subsequent nodes in the event flow. | Event
|  | stopPropagation():void Prevents processing of any event listeners in nodes subsequent to the current node in the event flow. | Event
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String [override] Returns a string that contains all the properties of the ProgressEvent object. | ProgressEvent
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Public Constants
Hide Inherited Public Constants
Show Inherited Public Constants

| Constant | Defined By
--- | --- | ---
|  | PROGRESS : String = "progress" [static] Defines the value of the type property of a progress event object. | ProgressEvent
|  | SOCKET_DATA : String = "socketData" [static] Defines the value of the type property of a socketData event object. | ProgressEvent
|  | STANDARD_ERROR_DATA : String = "standardErrorData" [static] Defines the value of the type property of a standardErrorData event object. | ProgressEvent
|  | STANDARD_INPUT_PROGRESS : String = "standardInputProgress" [static] Defines the value of the type property of a standardInputProgress event object. | ProgressEvent
|  | STANDARD_OUTPUT_DATA : String = "standardOutputData" [static] Defines the value of the type property of a standardOutputData event object. | ProgressEvent

Property Detail

### bytesLoaded

property

`bytesLoaded:Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The number of items or bytes loaded when the listener processes the event.

Implementation
`public function get bytesLoaded():Number`
`public function set bytesLoaded(value:Number):void`

### bytesTotal

property

`bytesTotal:Number`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

The total number of items or bytes that will be loaded if the loading process succeeds. If the progress event is dispatched/attached to a Socket object, the bytesTotal will always be 0 unless a value is specified in the bytesTotal parameter of the constructor. The actual number of bytes sent back or forth is not set and is up to the application developer.

Implementation
`public function get bytesTotal():Number`
`public function set bytesTotal(value:Number):void`
Constructor Detail

### ProgressEvent

()
Constructor

`public function ProgressEvent(type:String, bubbles:Boolean = false, cancelable:Boolean = false, bytesLoaded:Number = 0, bytesTotal:Number = 0)`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Creates an Event object that contains information about progress events. Event objects are passed as parameters to event listeners.

Parameters

| `type:String` — The type of the event. Possible values are:`ProgressEvent.PROGRESS`, `ProgressEvent.SOCKET_DATA`, `ProgressEvent.STANDARD_ERROR_DATA`, `ProgressEvent.STANDARD_INPUT_PROGRESS`, and `ProgressEvent.STANDARD_OUTPUT_DATA`.
| `bubbles:Boolean` (default = `false`)`` — Determines whether the Event object participates in the bubbling stage of the event flow.
| `cancelable:Boolean` (default = `false`)`` — Determines whether the Event object can be canceled.
| `bytesLoaded:Number` (default = `0`)`` — The number of items or bytes loaded at the time the listener processes the event.
| `bytesTotal:Number` (default = `0`)`` — The total number of items or bytes that will be loaded if the loading process succeeds.

Method Detail

### clone

()
method

`override public function clone():Event`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Creates a copy of the ProgressEvent object and sets each property's value to match that of the original.

Returns

| `Event` — A new ProgressEvent object with property values that match those of the original.

### toString

()
method

`override public function toString():String`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Returns a string that contains all the properties of the ProgressEvent object. The string is in the following format:

`[ProgressEvent type=value bubbles=value cancelable=value bytesLoaded=value bytesTotal=value]`

Returns

| `String` — A string that contains all the properties of the `ProgressEvent` object.

Constant Detail

### PROGRESS

Constant

`public static const PROGRESS:String = "progress"`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Defines the value of the `type` property of a `progress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`bytesLoaded` | The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal` | The total number of items or bytes that ultimately will be loaded if the loading process succeeds.
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event object with an event listener.
`target` | The object reporting progress.

Related API Elements

flash.display.LoaderInfo.progress
flash.media.Sound.progress
flash.net.FileReference.progress
flash.net.URLLoader.progress
flash.net.URLStream.progress

### SOCKET_DATA

Constant

`public static const SOCKET_DATA:String = "socketData"`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 1.0, Flash Player 9, Flash Lite 4

Defines the value of the `type` property of a `socketData` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event.
`bytesLoaded` | The number of items or bytes loaded at the time the listener processes the event.
`bytesTotal` | 0; this property is not used by `socketData` event objects.
`target` | The socket reporting progress.

Related API Elements

flash.net.Socket.socketData

### STANDARD_ERROR_DATA

Constant

`public static const STANDARD_ERROR_DATA:String = "standardErrorData"`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Defines the value of the `type` property of a `standardErrorData` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event.
`bytesLoaded` | The number of bytes of error data buffered by the NativeProcessObject.error due to this event.
`bytesTotal` | 0; this property is not used by `standardErrorData` event objects.
`target` | The NativeProcess object reporting error data.

Related API Elements

flash.desktop.NativeProcess.standardErrorData

### STANDARD_INPUT_PROGRESS

Constant

`public static const STANDARD_INPUT_PROGRESS:String = "standardInputProgress"`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Defines the value of the `type` property of a `standardInputProgress` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event.
`bytesLoaded` | The number of bytes of error data buffered by the NativeProcessObject.error due to this event.
`bytesTotal` | 0; this property is not used by `standardInputProgress` event objects.
`target` | The NativeProcess object reporting error data.

Related API Elements

flash.desktop.NativeProcess.standardInputProgress

### STANDARD_OUTPUT_DATA

Constant

`public static const STANDARD_OUTPUT_DATA:String = "standardOutputData"`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2, Flash Lite 4

Defines the value of the `type` property of a `standardOutputData` event object.

This event has the following properties:

Property | Value
--- | ---
`bubbles` | `false`
`cancelable` | `false`; there is no default behavior to cancel.
`currentTarget` | The object that is actively processing the Event.
`bytesLoaded` | The number of bytes of output data buffered by the NativeProcessObject.output due to this event.
`bytesTotal` | 0; this property is not used by `standardOutputData` event objects.
`target` | The NativeProcess object reporting output data.

Related API Elements

flash.desktop.NativeProcess.standardOutputData
Examples How to use this example
ProgressEventExample.as
The following example uses the `ProgressEventExample` class to illustrate how various event listeners are used when a file is being downloaded. The example carries out the following tasks:

1. The properties `downloadURL` and `fileName` are created, which indicate the location and name of the download file.
2. In the `ProgressEventExample` constructor, a new FileReference object named `file` is created and then passed to the `configureListeners()` method.
3. The `downloadURL` and `fileName` properties are then passed to `file.download()`, which prompts for the location to download the file.
4. The `configureListeners()` method adds seven event listeners and their associated subscriber methods:
   1. `cancel`/`cancelHandler()` is dispatched if the file download is canceled.
   2. `complete`/`complereHandler()` is dispatched when the file download process is finished.
   3. `ioError`/`ioErrorHandler()` is dispatched if the download file is unavailable or inaccessible.
   4. `open`/`openHandler()` is dispatched when the download operation has started.
   5. `progress`/`progressHandler()` is dispatched when the download process begins and again when it ends.
   6. `securityError`/`securityErrorHandler` is dispatched if the local playback security setting does not match the type of data access for the download file (local versus network); see the notes below.
   7. `select`/`selectHandler()` is dispatched when the download object is selected.

Notes:

- You need to compile the SWF file with Local Playback Security set to Access Network Files Only.
- This example requires a file named SomeFile.pdf.
- Although this example makes use of all events available to the FileReference object, most situations require only a subset.

Copy

    package {
        import flash.display.Sprite;
        import flash.events.*;
        import flash.net.FileReference;
        import flash.net.URLRequest;

        public class ProgressEventExample extends Sprite {
            private var downloadURL:String = "http://www.[yourDomain].com/SomeFile.pdf";
            private var fileName:String = "SomeFile.pdf";
            private var file:FileReference;

            public function ProgressEventExample() {
                var request:URLRequest = new URLRequest(downloadURL);
                file = new FileReference();
                configureListeners(file);
                file.download(request, fileName);
            }

            private function configureListeners(dispatcher:IEventDispatcher):void {
                dispatcher.addEventListener(Event.CANCEL, cancelHandler);
                dispatcher.addEventListener(Event.COMPLETE, completeHandler);
                dispatcher.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                dispatcher.addEventListener(Event.OPEN, openHandler);
                dispatcher.addEventListener(ProgressEvent.PROGRESS, progressHandler);
                dispatcher.addEventListener(SecurityErrorEvent.SECURITY_ERROR, securityErrorHandler);
                dispatcher.addEventListener(Event.SELECT, selectHandler);
            }

            private function cancelHandler(event:Event):void {
                trace("cancelHandler: " + event);
            }

            private function completeHandler(event:Event):void {
                trace("completeHandler: " + event);
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("ioErrorHandler: " + event);
            }

            private function openHandler(event:Event):void {
                trace("openHandler: " + event);
            }

            private function progressHandler(event:ProgressEvent):void {
                var file:FileReference = FileReference(event.target);
                trace("progressHandler: name=" + file.name + " bytesLoaded=" + event.bytesLoaded + " bytesTotal=" + event.bytesTotal);
            }

            private function securityErrorHandler(event:SecurityErrorEvent):void {
                trace("securityErrorHandler: " + event);
            }

            private function selectHandler(event:Event):void {
                var file:FileReference = FileReference(event.target);
                trace("selectHandler: name=" + file.name + " URL=" + downloadURL);
            }
        }
    }

© 2015 Adobe Systems Incorporated. All rights reserved.
Mon Apr 10 2017, 12:28 PM -07:00