Packageflash.media
Classpublic class CameraUI
InheritanceCameraUI Inheritance EventDispatcher Inheritance Object

Language version: ActionScript 3.0
Runtime version: 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.

See also

Michael Chaize: Android, AIR, and the Camera


Public Properties
 PropertyDefined by
 Inheritedconstructor : 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
 Inheritedprototype : Object
[static] A reference to the prototype object of a class or function object.
Object
Public Methods
 MethodDefined by
  
Creates a CameraUI object.
CameraUI
 Inherited
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
 Inherited
Dispatches an event into the event flow.
EventDispatcher
 Inherited
Checks whether the EventDispatcher object has any listeners registered for a specific type of event.
EventDispatcher
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
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
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
 Inherited
removeEventListener(type:String, listener:Function, useCapture:Boolean = false):void
Removes a listener from the EventDispatcher object.
EventDispatcher
  
Requests permission to access Camera UI.
CameraUI
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
 Inherited
Checks whether an event listener is registered with this EventDispatcher object or any of its ancestors for the specified event type.
EventDispatcher
Events
 EventSummaryDefined by
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application gains operating system focus and becomes active.EventDispatcher
   The cancel event is dispatched when the user closes the Camera UI without saving a picture or video.CameraUI
   The complete event is dispatched when the user either captures a still picture or video in the Camera UI.CameraUI
 Inherited [broadcast event] Dispatched when the Flash Player or AIR application operating loses system focus and is becoming inactive.EventDispatcher
   The error event is dispatched when the default camera cannot be opened.CameraUI
   Dispatched when the application requests permission to access Camera UI.CameraUI
Property detail
isSupportedproperty
isSupported:Boolean  [read-only]

Language version: ActionScript 3.0
Runtime version: 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
permissionStatusproperty 
permissionStatus:String  [read-only]

Language version: ActionScript 3.0
Runtime version: AIR 24.0

Determine whether the application has been granted the permission to use camera.

Implementation
    public static function get permissionStatus():String

See also

Constructor detail
CameraUI()constructor
public function CameraUI()

Language version: ActionScript 3.0
Runtime version: AIR 2.5

Creates a CameraUI object.

Method detail
launch()method
public function launch(requestedMediaType:String):void

Language version: ActionScript 3.0
Runtime version: 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.

See also

requestPermission()method 
public function requestPermission():void

Language version: ActionScript 3.0
Runtime version: 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
cancelevent 
Event object type: flash.events.Event
Event.type property = flash.events.Event.CANCEL

Language version: ActionScript 3.0
Runtime version: 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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetA reference to the object on which the operation is canceled.
completeevent  
Event object type: flash.events.MediaEvent
MediaEvent.type property = flash.events.MediaEvent.COMPLETE

Language version: ActionScript 3.0
Runtime version: 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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
dataThe MediaPromise object of the available media instance.
errorevent  
Event object type: flash.events.ErrorEvent
ErrorEvent.type property = flash.events.ErrorEvent.ERROR

Language version: ActionScript 3.0
Runtime version: 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:

PropertyValue
bubblesfalse
cancelablefalse; there is no default behavior to cancel.
currentTargetThe object that is actively processing the Event object with an event listener.
targetThe object experiencing a network operation failure.
textText to be displayed as an error message.
permissionStatusevent  
Event object type: flash.events.PermissionEvent

Language version: ActionScript 3.0
Runtime version: 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

See also

Examples
examples\CameraUIExample.Still.1
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.
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();
	  	}
 	}
}