flash.media

# CameraRoll - AS3

Package | flash.media
Class | public class CameraRoll
Inheritance | CameraRoll EventDispatcher Object

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

The CameraRoll class allows you to access image data in the system media library or "camera roll."

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. See AIR Profile Support for more information regarding API support across multiple profiles.

The `CameraRoll.addBitmapData()` method adds an image to the device's dedicated media library. To check at run time whether your application supports the `CameraRoll.addBitmapData()` method, check the `CameraRoll.supportsAddBitmapData` property.

The `CameraRoll.browseForImage()` method opens an image-choosing dialog that allows a user to choose an image in the media library. When the user selects an image, the CameraRoll object dispatches a `select` event. Use the MediaEvent object dispatched for this event to access the chosen image. To check at run time whether your application supports the `CameraRoll.browseForImage()` method, check the `CameraRoll.supportsBrowseForImage` property.

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
|  | permissionStatus : String [static] [read-only] Determine whether the application has been granted the permission to access camera roll. | CameraRoll
|  | supportsAddBitmapData : Boolean [static] [read-only] Whether the CameraRoll.addBitmapData() method is supported. | CameraRoll
|  | supportsBrowseForImage : Boolean [static] [read-only] Reports whether the CameraRoll.browseForImage() method is supported. | CameraRoll

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | CameraRoll() Creates a CameraRoll object. | CameraRoll
|  | addBitmapData(bitmapData:BitmapData):void Adds an image to the device camera roll. | CameraRoll
|  | 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
|  | browseForImage(value:CameraRollBrowseOptions = null):void Opens an image browser dialog to allow the user to select an existing image from the device camera roll. | CameraRoll
|  | 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
|  | 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
|  | requestPermission():void Requests permission to access system media library or "camera roll". | CameraRoll
|  | 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
|  | cancel | Dispatched when a user cancels a browse-for-image operation without selecting an image. | CameraRoll
|  | complete | Signals that an addBitmapData() operation completed successfully. | CameraRoll
|  | deactivate | [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive. | EventDispatcher
|  | error | The error event is dispatched when an error occurs. | CameraRoll
|  | permissionStatus | Dispatched when the application requests permission to access camera roll. | CameraRoll
|  | select | Dispatched when a user selects an image from the device media library. | CameraRoll

Property Detail

### permissionStatus

property

`permissionStatus:String` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 24.0

Determine whether the application has been granted the permission to access camera roll.

Implementation
`public static function get permissionStatus():String`

Related API Elements

flash.permissions.PermissionStatus

### supportsAddBitmapData

property

`supportsAddBitmapData:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Whether the `CameraRoll.addBitmapData()` method is supported. Currently, the feature is only supported in AIR applications on mobile devices.

Implementation
`public static function get supportsAddBitmapData():Boolean`

### supportsBrowseForImage

property

`supportsBrowseForImage:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Reports whether the `CameraRoll.browseForImage()` method is supported. Currently, the feature is only supported in AIR applications on mobile devices.

Implementation
`public static function get supportsBrowseForImage():Boolean`
Constructor Detail

### CameraRoll

()
Constructor

`public function CameraRoll()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Creates a CameraRoll object.

There is only a single media library supported by ActionScript. All CameraRoll objects save to the same image repository.

Method Detail

### addBitmapData

()
method

`public function addBitmapData(bitmapData:BitmapData):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Adds an image to the device camera roll.

To check at run time whether your application supports the `CameraRoll.addBitmapData()` method, check the `CameraRoll.supportsAddBitmapData` property.

Parameters

| `bitmapData:BitmapData` — a BitmapData object containing the image to send to the camera roll.

Throws

| `PermissionError` — The application does not have permission to use camera.

### browseForImage

()
method

`public function browseForImage(value:CameraRollBrowseOptions = null):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Opens an image browser dialog to allow the user to select an existing image from the device camera roll.

When the user selects an image, this CameraRoll instance dispatches a `select` event containing a MediaEvent object. Use the `data` property of the MediaEvent object to load the image. The `data` property is a MediaPromise object, which you can load using the `loadFilePromise()` method of the Loader class. Note that the MediaPromise object contains a valid file object on some platforms (Blackberry Tablet OS), but not on others (iOS and Android). When you use the `loadFilePromise()` method, the image is loaded properly on all platforms. To access the raw data from the media object, you can open the data source provided by the media promise and read the data using the methods from the IDataInput interface.

To check at run time whether your application supports the `CameraRoll.browseForImage()` method, check the `CameraRoll.supportsBrowseForImage` property.

On iOS (and only on the iPad) you can request a specific size for the image browser dialog. You can also specify an area of the screen that you don't want the image browser dialog to cover. This request works only on the iPad, because on that device the image browser does not occupy the entire screen.

To request size and placement options for the image browser (for iPad), pass a CameraRollBrowseOptions object to `browseForImage()`. With no parameters, this method positions the dialog in the display's top-left corner, using system defaults for the dialog's dimensions.

Parameters

| `value:CameraRollBrowseOptions` (default = `null`)`` — A CameraRollBrowseOptions object that you can use to specify options for displaying the image roll dialog. This parameter is optional.

Events

| `select:`MediaEvent`` — Dispatched when the user chooses an image.
| `cancel:`Event`` — Dispatched when a user cancels the browse operation.
| `error:`ErrorEvent`` — Dispatched if the default image browser application is already in use.
| `error:`ErrorEvent`` — Dispatched if the AIR application is in the background when it calls this function.

Throws

| `PermissionError` — The application does not have permission to use camera.

Learn more

Uploading images from CameraRoll and CameraUI

Related API Elements

MediaEvent
MediaPromise
Loader.loadFilePromise()
Example ( How to use this example )
Copy

    package flash.media.examples
    {
            import flash.media.CameraRoll;
            import flash.media.MediaPromise;
            import flash.media.MediaType;
            import flash.events.MediaEvent;
            import flash.events.Event;
            import flash.display.Loader;
            import flash.display.Sprite;
            import flash.events.IOErrorEvent;
            import flash.display.StageAlign;
            import flash.display.StageScaleMode;

            public class CameraRollTest extends Sprite{
                private var mediaSource:CameraRoll = new CameraRoll();

                public function CameraRollTest() {
                    this.stage.align = StageAlign.TOP_LEFT;
                    this.stage.scaleMode = StageScaleMode.NO_SCALE;

                    if( CameraRoll.supportsBrowseForImage )
                    {
                        log( "Browsing for image..." );
                        mediaSource.addEventListener( MediaEvent.SELECT, imageSelected );
                        mediaSource.addEventListener( Event.CANCEL, browseCanceled );

                        mediaSource.browseForImage();
                    }
                    else
                    {
                        log( "Browsing in camera roll is not supported.");
                    }
                }

                private var imageLoader:Loader;
                private function imageSelected( event:MediaEvent ):void
                {
                    log( "Image selected..." );

                    var imagePromise:MediaPromise = event.data;

                    imageLoader = new Loader();
                    if( imagePromise.isAsync )
                    {
                        log( "Asynchronous media promise." );
                        imageLoader.contentLoaderInfo.addEventListener( Event.COMPLETE, imageLoaded );
                        imageLoader.contentLoaderInfo.addEventListener( IOErrorEvent.IO_ERROR, imageLoadFailed );
                        imageLoader.loadFilePromise( imagePromise );
                    }
                    else
                    {
                        log( "Synchronous media promise." );
                        imageLoader.loadFilePromise( imagePromise );
                        this.addChild( imageLoader );
                    }
                }

                private function browseCanceled( event:Event ):void
                {
                    log( "Image browse canceled." );
                }

                private function imageLoaded( event:Event ):void
                {
                    log( "Image loaded asynchronously." );
                    this.addChild( imageLoader );
                }

                private function imageLoadFailed( event:Event ):void
                {
                    log( "Image load failed." );
                }

                private function log( text:String ):void
                {
                    trace( text );
                }

            }

        }

### requestPermission

()
method

`public function requestPermission():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 24.0

Requests permission to access system media library or "camera roll".

Events

| `PermissionStatus:`PermissionEvent`` — dispatched when the requested permission is granted/denied by the user.

Event Detail

### cancel

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Dispatched when a user cancels a browse-for-image operation without selecting an image.

The `Event.CANCEL` constant defines the value of the `type` property of a `cancel` 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` | A reference to the object on which the operation is canceled.

### complete

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

Signals that an addBitmapData() operation completed successfully.

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.

### error

Event

Event Object Type: `flash.events.ErrorEvent`
property ErrorEvent.type = `flash.events.ErrorEvent.ERROR`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2

The `error` event is dispatched when an error occurs.

Sources of errors include:

- An image browser cannot be opened.
- An image browser is already in use.
- The AIR application attempts to browse for an image while in the background.
- An image cannot be added to the media library.
- A method is called that is not supported on the device.
- The AIR application attempts to load a remote image without an internet connection.

Defines the value of the `type` property of an `error` 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 experiencing a network operation failure.
`text` | Text to be displayed as an error message.

### permissionStatus

Event

Event Object Type: `flash.events.PermissionEvent`
property PermissionEvent.type = `flash.events.PermissionEvent.PERMISSION_STATUS`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 24.0

Dispatched when the application requests permission to access camera roll. Check the value of `status` property to determine whether the permission was granted or denied

Related API Elements

CameraRoll.requestPermission()
flash.permissions.PermissionStatus

### select

Event

Event Object Type: `flash.events.MediaEvent`
property MediaEvent.type = `flash.events.MediaEvent.SELECT`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Dispatched when a user selects an image from the device media library.

The MediaEvent object dispatched for this event provides access to the chosen media.

A constant for the `select` MediaEvent.

Defines the value of the `type` property of a `MediaEvent` 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.
`data` | The MediaPromise object of the available media instance.

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