flash.media

# MediaPromise - AS3

Package | flash.media
Class | public class MediaPromise
Inheritance | MediaPromise EventDispatcher Object
Implements | IFilePromise

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The MediaPromise class represents the promise to deliver a media object.

The `data` property of a MediaEvent object is a MediaPromise instance. You can use the MediaPromise methods to access the promised media object. Supported media formats include still images and video.

You cannot create a MediaPromise object. Calling `new MediaPromise()` generates a run-time error.

Related API Elements

MediaEvent
IFilePromise
Loader.LoadFilePromise()
IDataInput
CameraRoll.browseForImage()
CameraUI

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | file : File [read-only] The File instance representing the media object, if one exists. | MediaPromise
|  | isAsync : Boolean [read-only] Reports whether the underlying data source is asynchronous or synchronous. | MediaPromise
|  | mediaType : String [read-only] The general type of media, either image or video. | MediaPromise
|  | relativePath : String [read-only] The file name of the media object, if one exists. | MediaPromise

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | addEventListener(type:String, listener:Function, useCapture:Boolean = false, priority:int = 0, useWeakReference:Boolean = false):void Registers an event listener object with an EventDispatcher object so that the listener receives notification of an event. | EventDispatcher
|  | close():void Closes the data source. | MediaPromise
|  | dispatchEvent(event:Event):Boolean Dispatches an event into the event flow. | EventDispatcher
|  | hasEventListener(type:String):Boolean Checks whether the EventDispatcher object has any listeners registered for a specific type of event. | EventDispatcher
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | 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
|  | open():IDataInput Opens the underlying data source and returns the IDataInput instance allowing you to read it. | MediaPromise
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void Removes a listener from the EventDispatcher object. | EventDispatcher
|  | reportError(e:ErrorEvent):void Used by the runtime to report errors. | MediaPromise
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toLocaleString():String Returns the string representation of this object, formatted according to locale-specific conventions. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object
|  | willTrigger(type:String):Boolean Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type. | EventDispatcher

Events
Click for more information on events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | activate | [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active. | EventDispatcher
|  | close | A MediaPromise object dispatches a close event when the underlying data stream has closed. | MediaPromise
|  | complete | A MediaPromise object dispatches a complete event when all data has been read. | MediaPromise
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | ioError | A MediaPromise object dispatches an ioError event when an error is encountered while reading the underlying data stream. | MediaPromise
|  | progress | A MediaPromise object dispatches progress events as the data becomes available. | MediaPromise

Property Detail

### file

property

`file:File` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The File instance representing the media object, if one exists.

This property references a File object if the underlying data source is file-based and the file is accessible to your application. Otherwise, the property is `null`.

Implementation
`public function get file():File`

### isAsync

property

`isAsync:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Reports whether the underlying data source is asynchronous or synchronous.

Implementation
`public function get isAsync():Boolean`

### mediaType

property

`mediaType:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The general type of media, either image or video.

The constants in the MediaType class define possible values of this property:

- MediaType.IMAGE
- MediaType.VIDEO

Implementation
`public function get mediaType():String`

Related API Elements

MediaType

### relativePath

property

`relativePath:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The file name of the media object, if one exists.

A file name is available if the underlying data source is file-based and the file is accessible to your application. Otherwise, the property is `null`.

Implementation
`public function get relativePath():String`
Method Detail

### close

()
method

`public function close():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Closes the data source.

### open

()
method

`public function open():IDataInput`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Opens the underlying data source and returns the IDataInput instance allowing you to read it.

If the underlying data source is asynchronous, then the MediaPromise object dispatches `progress` and `complete` events to indicate whether data is available to be read. If the data source is synchronous, all data is available immediately and these events are not dispatched.

Note: You can load a MediaPromise object using the `loadFilePromise()` method of the Loader class instead of reading the data manually.

Returns

| `IDataInput`

Related API Elements

Loader.loadFilePromise()

### reportError

()
method

`public function reportError(e:ErrorEvent):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Used by the runtime to report errors.

Application code should not call this method.

Parameters

| `e:ErrorEvent` — the error vent to dispatch.

Event Detail

### close

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.CLOSE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

A MediaPromise object dispatches a `close` event when the underlying data stream has closed.

The `Event.CLOSE` constant defines the value of the `type` property of a `close` 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 object with an event listener.
`target` | The object whose connection has been closed.

### complete

Event

Event Object Type: `flash.events.Event`
property Event.type = `flash.events.Event.COMPLETE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

A MediaPromise object dispatches a `complete` event when all data has been read. The event indicates that there is no more data available in the underlying stream.

A `complete` event is not dispatched by a synchronous data source.

The `Event.COMPLETE` constant defines the value of the `type` property of a `complete` 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 object with an event listener.
`target` | The network object that has completed loading.

### ioError

Event

Event Object Type: `flash.events.IOErrorEvent`
property IOErrorEvent.type = `flash.events.IOErrorEvent.IOERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

A MediaPromise object dispatches an `ioError` event when an error is encountered while reading the underlying data stream. No more data can be read after this event is dispatched.

### progress

Event

Event Object Type: `flash.events.ProgressEvent`
property ProgressEvent.type = `flash.events.ProgressEvent.PROGRESS`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

A MediaPromise object dispatches `progress` events as the data becomes available.

The `bytesTotal` property of all progress events except the last has the value 0. If all the data is available immediately, no `progress` events may be dispatched. No `progress` events are dispatched by synchronous data sources.

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.

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