flash.media

# CameraUI - AS3

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The CameraUI class allows you to capture a still image or video using the default camera application on a device.

The `launch()` method requests that the device open the default camera application. The captured image or video is available in the MediaEvent object dispatched for the complete event. Since the default camera application can save the image or video in a variety of formats, there is no guarantee that returned media object can be loaded and displayed by the AIR runtime.

On some platforms, the media object returned by the camera is accessible as a file-based media promise. On others, the media promise is not file-based and the `file` and `relativePath` properties of the MediaPromise object are `null`. Do not use these properties in code that is used on more than one platform.

On Android, the default camera application does not open if the external storage card is not available (such as when the user has mounted the card as a USB mass storage device). In addition, the AIR application that launches the camera loses focus. If the device runs low on resources, the AIR application can be terminated by the operating system before the media capture is complete.

On some platforms, the media object is automatically stored in the device media library. On platforms on which images and video are not automatically stored by the default camera application, you can use the CameraRoll `addBitmapData()` function to store the media object.

AIR profile support: This feature is supported on mobile devices, but it is not supported on desktop operating systems or AIR for TV devices. You can test for support at run time using the `CameraUI.isSupported` property. See AIR Profile Support for more information regarding API support across multiple profiles.

View the examples

Learn more

Michael Chaize: Android, AIR, and the Camera

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
|  | isSupported : Boolean [static] [read-only] Reports whether the CameraUI class is supported on the current device. | CameraUI
|  | permissionStatus : String [static] [read-only] Determine whether the application has been granted the permission to use camera. | CameraUI

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | CameraUI() Creates a CameraUI object. | CameraUI
|  | 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
|  | 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
|  | launch(requestedMediaType:String):void Launches the default camera application on the device. | CameraUI
|  | 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 Camera UI. | CameraUI
|  | 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 | The cancel event is dispatched when the user closes the Camera UI without saving a picture or video. | CameraUI
|  | complete | The complete event is dispatched when the user either captures a still picture or video in the Camera UI. | CameraUI
|  | 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 the default camera cannot be opened. | CameraUI
|  | permissionStatus | Dispatched when the application requests permission to access Camera UI. | CameraUI

Property Detail

### isSupported

property

`isSupported:Boolean` [read-only]

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Reports whether the CameraUI class is supported on the current device. Currently, the feature is only supported in AIR applications on Android.

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

### 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 use camera.

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

Related API Elements

flash.permissions.PermissionStatus
Constructor Detail

### CameraUI

()
Constructor

`public function CameraUI()`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Creates a CameraUI object.

Method Detail

### launch

()
method

`public function launch(requestedMediaType:String):void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

Launches the default camera application on the device.

You can capture either still images or video with this class. Video capture uses the "Quality Low" camcorder profile on the device.

When the `launch()` method is called, the default camera application on the device is invoked. The AIR application loses focus and waits for the user to capture a still image or to finish capturing video. Once the desired media is captured by the user, the AIR application regains focus and this CameraUI object dispatches a `complete` event. If the user cancels the operation, this CameraUI object dispatches a `cancel` event instead.

Note: It is possible for the AIR application to be shut down by the Android operating system while it is in the background waiting for the user to capture an image or video. If this happens, the user must restart the application. The AIR application does not dispatch a media event for the previous image capture.

You can access the captured media file using the `data` property of the MediaEvent object dispatched for the `complete` event. This property is an instance of the MediaPromise class, which you can load into your application using the `loadFilePromise()` method of the Loader class. Note that the device camera can save captured media in a variety of formats. Video is particularly problematic in this regard. It might not be possible to display the captured media in AIR.

Parameters

| `requestedMediaType:String` — The type of media object to capture. The valid values for this parameter are defined in the MediaType class:

- `MediaType.IMAGE`
- `MediaType.VIDEO`

Events

| `complete:`MediaEvent`` — Dispatched when a media object is captured.
| `cancel:`Event`` — Dispatched when the user exits from the native camera without capturing a media object.
| `error:`ErrorEvent`` — Dispatched if the default camera 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.

Related API Elements

MediaType
MediaPromise
Loader.loadFilePromise()

### requestPermission

()
method

`public function requestPermission():void`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 24.0

Requests permission to access Camera UI.

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

The `cancel` event is dispatched when the user closes the Camera UI without saving a picture or video.

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.MediaEvent`
property MediaEvent.type = `flash.events.MediaEvent.COMPLETE`

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The `complete` event is dispatched when the user either captures a still picture or video in the Camera UI.

A constant for the `complete` 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.

### error

Event

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

Language Version: | ActionScript 3.0

Runtime Versions: | AIR 2.5

The `error` event is dispatched when the default camera cannot be opened.

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 UI. Check the value of `status` property to check whether the permission was granted or denied

Related API Elements

CameraUI.requestPermission()
flash.permissions.PermissionStatus
Examples How to use this example
CameraUIExample.Still.1.as
The following example uses the CameraUI class to launch the default camera application on the device. When a picture is taken by the user, the example places the image on the display list.
Copy

    package  {
     import flash.desktop.NativeApplication;
     import flash.display.Loader;
     import flash.display.MovieClip;
     import flash.display.StageAlign;
     import flash.display.StageScaleMode;
     import flash.events.ErrorEvent;
     import flash.events.Event;
     import flash.events.IOErrorEvent;
     import flash.events.MediaEvent;
     import flash.media.CameraUI;
     import flash.media.MediaPromise;
     import flash.media.MediaType;

         public class CameraUIStillImage extends MovieClip{

              private var deviceCameraApp:CameraUI = new CameraUI();
              private var imageLoader:Loader;

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

                   if( CameraUI.isSupported )
                   {
                    trace( "Initializing camera..." );

                    deviceCameraApp.addEventListener( MediaEvent.COMPLETE, imageCaptured );
                    deviceCameraApp.addEventListener( Event.CANCEL, captureCanceled );
                    deviceCameraApp.addEventListener( ErrorEvent.ERROR, cameraError );
                    deviceCameraApp.launch( MediaType.IMAGE );
                   }
                   else
                   {
                    trace( "Camera interface is not supported.");
                   }
              }

              private function imageCaptured( event:MediaEvent ):void
              {
                   trace( "Media captured..." );

                   var imagePromise:MediaPromise = event.data;

                   if( imagePromise.isAsync )
                   {
                    trace( "Asynchronous media promise." );
                    imageLoader = new Loader();
                    imageLoader.contentLoaderInfo.addEventListener( Event.COMPLETE, asyncImageLoaded );
                    imageLoader.addEventListener( IOErrorEvent.IO_ERROR, cameraError );

                    imageLoader.loadFilePromise( imagePromise );
                   }
                   else
                   {
                    trace( "Synchronous media promise." );
                    imageLoader.loadFilePromise( imagePromise );
                    showMedia( imageLoader );
                   }
              }

              private function captureCanceled( event:Event ):void
              {
                   trace( "Media capture canceled." );
                   NativeApplication.nativeApplication.exit();
              }

              private function asyncImageLoaded( event:Event ):void
              {
                   trace( "Media loaded in memory." );
                   showMedia( imageLoader );
              }

              private function showMedia( loader:Loader ):void
              {
                   this.addChild( loader );
              }

              private function cameraError( error:ErrorEvent ):void
              {
                   trace( "Error:" + error.text );
                   NativeApplication.nativeApplication.exit();
              }
         }
    }

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