Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/UIKit.framework |
Availability | Available in iOS 2.0 and later. |
Declared in | UIImagePickerController.h |
The UIImagePickerController
class manages system-supplied user interfaces for choosing and taking pictures and movies on supported devices. The class manages user interactions and delivers the results of those interactions to the delegate object you’ve associated with the image picker.
To use the default image picker to handle user interactions, perform these steps:
Verify that the device is capable of picking content from the desired source. Do this calling the isSourceTypeAvailable:
class method.
Check which media types are available for the source type by calling the availableMediaTypesForSourceType:
class method. This lets you distinguish between a camera that can be used for video recording and one that can be used only for still images.
Tell the UIImagePickerController
class which user interface to display. Do this by setting the mediaTypes
property.
Present the user interface.
When the user picks an image or movie, or cancels the operation, dismiss the image picker using your delegate object.
In addition to the default image picker, in iOS 3.1 and later you can manage user interactions yourself. To do this, provide an overlay view to display a custom picture-taking interface. This lets you initiate choosing and taking pictures and movies programmatically. Your custom overlay view can be displayed in addition to, or instead of, the default controls provided by the image picker interface.
To use this class, you must provide a delegate that conforms to the UIImagePickerControllerDelegate
protocol. See UIImagePickerControllerDelegate Protocol Reference.
The default camera interface supports editing of previously-saved movies. Editing involves trimming from the start or end of the movie, then saving the trimmed movie.
In iOS 4.0 and later, you can provide custom controls to let the user adjust flash mode (on devices that have a flash LED), pick which camera to use (on devices that have a front and rear camera), and switch between still image and movie capture. You can also manage these settings programmatically.
In iOS 4.0 and later, on devices that have a flash LED, you can manipulate the flash directly to provide effects such as a strobe light. Present a picker interface set to use video capture mode. Then, turn the flash LED on or off by setting the cameraFlashMode
property to UIImagePickerControllerCameraFlashModeOn
or UIImagePickerControllerCameraFlashModeOff
.
Movie capture has a default duration limit of 10 minutes but can be adjusted using the videoMaximumDuration
property. When a user taps the Share button to send a movie to MMS, MobileMe, YouTube, or another destination, an appropriate duration limit and an appropriate video quality are enforced.
To display an interface dedicated to movie editing, rather than one that also supports recording new movies, use the UIVideoEditorController
class instead of this one. See UIVideoEditorController Class Reference.
Important: The UIImagePickerController
class supports portrait mode only. This class is intended to be used as-is and does not support subclassing. The view hierarchy for this class is private and must not be modified, with one exception. In iOS 3.1 and later, you can assign a custom view to the cameraOverlayView
property and use that view to present additional information or manage the interactions between the camera interface and your code.
allowsEditing
property
delegate
property
mediaTypes
property
allowsImageEditing
property Deprecated in iOS 3.1
videoQuality
property
videoMaximumDuration
property
showsCameraControls
property
cameraOverlayView
property
cameraViewTransform
property
For more about Objective-C properties, see “Properties” in The Objective-C Programming Language.
A Boolean value indicating whether the user is allowed to edit a selected still image or movie.
@property(nonatomic) BOOL allowsEditing
If you allow the user to edit still images or movies, the delegate may receive a dictionary with information about the edits that were made. The protocol for the delegate is described in UIImagePickerControllerDelegate Protocol Reference.
This property is set to NO
by default.
UIImagePickerController.h
The capture mode used by the camera.
@property(nonatomic) UIImagePickerControllerCameraCaptureMode cameraCaptureMode
The various capture modes are listed in the “UIImagePickerControllerCameraCaptureMode” enumeration. The default value is UIImagePickerControllerCameraCaptureModePhoto
.
UIImagePickerController.h
The camera used by the image picker controller.
@property(nonatomic) UIImagePickerControllerCameraDevice cameraDevice
The default is UIImagePickerControllerCameraDeviceRear
.
UIImagePickerController.h
The flash mode used by the active camera.
@property(nonatomic) UIImagePickerControllerCameraFlashMode cameraFlashMode
The various flash modes are listed in the “UIImagePickerControllerCameraFlashMode” enumeration. The default value is UIImagePickerControllerCameraFlashModeAuto
.
The value of this property specifies the behavior of the still-image flash when the value of the cameraCaptureMode
property is UIImagePickerControllerCameraCaptureModePhoto
, and specifies the behavior of the video torch when cameraCaptureMode
is UIImagePickerControllerCameraCaptureModeVideo
.
UIImagePickerController.h
The custom view to display on top of the default image picker interface.
@property(nonatomic, retain) UIView *cameraOverlayView
You can use an overlay view to present a custom view hierarchy on top of the default image picker interface. The image picker layers your custom overlay view on top of the other image picker views and positions it relative to the screen coordinates. If you have the default camera controls set to be visible, incorporate transparency into your view, or position it to avoid obscuring the underlying content.
This property is set to nil
by default.
You can access this property only when the source type of the image picker is set to UIImagePickerControllerSourceTypeCamera
. Attempting to access this property for other source types results in the throwing of an NSInvalidArgumentException
exception.
UIImagePickerController.h
The transform to apply to the camera’s preview image.
@property(nonatomic) CGAffineTransform cameraViewTransform
This transform affects the live preview image only and does not affect your custom overlay view or the default image picker controls. You can use this property in conjunction with custom controls to implement your own electronic zoom behaviors.
You can access this property only when the source type of the image picker is set to UIImagePickerControllerSourceTypeCamera
. Attempting to access this property for other source types results in the throwing of an NSInvalidArgumentException
exception.
UIImagePickerController.h
The image picker’s delegate object.
@property(nonatomic, assign) id<UINavigationControllerDelegate, UIImagePickerControllerDelegate> delegate
The delegate receives notifications when the user picks an image or movie, or exits the picker interface. The delegate also decides when to dismiss the picker interface, so you must provide a delegate to use a picker. If this property is nil
, the picker is dismissed immediately if you try to show it.
For information about the methods you can implement for your delegate object, see UIImagePickerControllerDelegate Protocol Reference.
UIImagePickerController.h
An array indicating the media types to be accessed by the picker interface.
@property(nonatomic, copy) NSArray *mediaTypes
Depending on the media types you assign to this property, the picker displays the still camera or the movie camera interface, or a selection control that lets the user choose the picker interface. Before setting this property, check which media types are available by calling the availableMediaTypesForSourceType:
class method.
By default, this property is set to the single value kUTTypeImage
, which designates the still camera interface.
If you set this property to an empty array, or to an array in which none of the media types is available for the current source, the system throws an exception.
UIImagePickerController.h
Indicates whether the image picker displays the default camera controls.
@property(nonatomic) BOOL showsCameraControls
The default value of this property is YES
, which specifies that the default camera controls are visible in the picker. Set it to NO
to hide the default controls if you want to instead provide a custom overlay view using the cameraOverlayView
property.
Note: In iOS 3.1.3 and earlier, hiding the default camera controls limits you to taking still pictures only, regardless of whether movie capture is available on the device.
If you set this property to NO
and provide your own custom controls, you can take multiple pictures before dismissing the image picker interface. However, if you set this property to YES
, your delegate must dismiss the image picker interface after the user takes one picture or cancels the operation.
You can access this property only when the source type of the image picker is set to UIImagePickerControllerSourceTypeCamera
. Attempting to access this property for other source types results in the throwing of an NSInvalidArgumentException
exception. Depending on the value you assign to the mediaTypes
property, the default controls display the still camera or movie camera interface, or a selection control that lets the user choose the picker interface.
UIImagePickerController.h
The type of picker interface displayed by the controller.
@property(nonatomic) UIImagePickerControllerSourceType sourceType
Prior to running the picker interface, set this value to the desired source type. The specified source type must be available and an exception is thrown if it is not. If you change this property while the picker is visible, the picker interface changes to match the new value in this property.
The various source types are listed in the “UIImagePickerControllerSourceType” enumeration. The default value is UIImagePickerControllerSourceTypePhotoLibrary
.
UIImagePickerController.h
The maximum duration, in seconds, for a video recording.
@property(nonatomic) NSTimeInterval videoMaximumDuration
The default value for this property is 10 minutes (600 seconds). When a user taps the Share button to send a movie to MMS, MobileMe, YouTube, or another destination, an appropriate duration limit and an appropriate video quality are enforced.
This property is available only if the mediaTypes
property’s value array includes the kUTTypeMovie
media type.
UIImagePickerController.h
The video recording and transcoding quality.
@property(nonatomic) UIImagePickerControllerQualityType videoQuality
The video quality setting specified by this property is used during video recording. It is also used whenever picking a recorded movie. Specifically, if the video quality setting is lower than the video quality of an existing movie, displaying that movie in the picker results in transcoding the movie to the lower quality.
The various video qualities are listed in the “UIImagePickerControllerQualityType”
enumeration. The default value is UIImagePickerControllerQualityTypeMedium
. To capture or transcode a movie using a video quality other than the default value, you must set the quality explicitly.
This property is available only if the mediaTypes
property’s value array includes the kUTTypeMovie
media type.
UIImagePickerController.h
Returns an array of NSNumber
objects indicating the capture modes supported by a given camera device.
+ (NSArray *)availableCaptureModesForCameraDevice:(UIImagePickerControllerCameraDevice)cameraDevice
A “UIImagePickerControllerCameraDevice” constant indicating the camera you want to interrogate.
An array of NSNumber
objects indicating the capture modes supported by cameraDevice.
See “UIImagePickerControllerCameraCaptureMode” for possible values.
UIImagePickerController.h
Returns an array of the available media types for the specified source type.
+ (NSArray *)availableMediaTypesForSourceType:(UIImagePickerControllerSourceType)sourceType
The source to use to pick an image.
An array whose elements identify the available media types for the specified source type.
Some iOS devices support video recording. Use this method, along with the isSourceTypeAvailable:
method, to determine if video recording is available on a device. The availability of video recording is indicated by the presence of the kUTTypeMovie
media type for the UIImagePickerControllerSourceTypeCamera
source type.
UIImagePickerController.h
Returns a Boolean value that indicates whether a given camera is available.
+ (BOOL)isCameraDeviceAvailable:(UIImagePickerControllerCameraDevice)cameraDevice
A “UIImagePickerControllerCameraDevice” constant indicating the camera whose availability you want to check.
YES
if the camera indicated by cameraDevice is available, or NO
if it is not available.
UIImagePickerController.h
Indicates whether a given camera has flash illumination capability.
+ (BOOL)isFlashAvailableForCameraDevice:(UIImagePickerControllerCameraDevice)cameraDevice
A “UIImagePickerControllerCameraDevice” constant indicating the camera whose flash capability you want to know.
YES
if cameraDevice can use flash illumination, or NO
if it cannot.
UIImagePickerController.h
Returns a Boolean value indicating whether the device supports picking media using the specified source type.
+ (BOOL)isSourceTypeAvailable:(UIImagePickerControllerSourceType)sourceType
The source to use to pick an image or movie.
YES
if the device supports the specified source type; NO
if the specified source type is not available.
Because a media source may not be present or may be unavailable, devices may not always support all source types. For example, if you attempt to pick an image from the user’s library and the library is empty, this method returns NO
. Similarly, if the camera is already in use, this method returns NO
.
Before attempting to use an UIImagePickerController
object to pick an image, you must call this method to ensure that the desired source type is available.
UIImagePickerController.h
Starts video capture using the camera specified by the UIImagePickerControllerCameraDevice
property.
- (BOOL)startVideoCapture
YES
on success or NO
on failure. This method may return a value of NO
for various reasons, among them the following:
Movie capture is already in progress
The device does not support movie capture
The device is out of disk space
Use this method in conjunction with a custom overlay view to initiate the programmatic capture of a movie. You can take more than one movie without leaving the interface, but to do so requires you to hide the default image picker controls.
Calling this method while a movie is being captured has no effect. You must can the stopVideoCapture
method, and then wait until the associated delegate object receives an imagePickerController:didFinishPickingMediaWithInfo:
message, before you can capture another movie.
Calling this method when the source type of the image picker is set to a value other than UIImagePickerControllerSourceTypeCamera
results in the throwing of an NSInvalidArgumentException
exception.
If you require additional options or more control over movie capture, use the movie capture methods in the AV Foundation framework. Refer to AV Foundation Framework Reference.
UIImagePickerController.h
Stops video capture.
- (void)stopVideoCapture
After you call this method to stop video capture, the system calls the image picker delegate’s imagePickerController:didFinishPickingMediaWithInfo:
method.
UIImagePickerController.h
Captures a still image using the camera.
- (void)takePicture
Use this method in conjunction with a custom overlay view to initiate the programmatic capture of a still image. This supports taking more than one picture without leaving the interface, but requires that you hide the default image picker controls.
Calling this method while an image is being captured has no effect. You must wait until the associated delegate object receives an imagePickerController:didFinishPickingMediaWithInfo:
message before you can capture another picture.
Calling this method when the source type of the image picker is set to a value other than UIImagePickerControllerSourceTypeCamera
results in the throwing of an NSInvalidArgumentException
exception.
UIImagePickerController.h
The source to use when picking an image.
enum { UIImagePickerControllerSourceTypePhotoLibrary, UIImagePickerControllerSourceTypeCamera, UIImagePickerControllerSourceTypeSavedPhotosAlbum }; typedef NSUInteger UIImagePickerControllerSourceType;
UIImagePickerControllerSourceTypePhotoLibrary
Pick an image or movie, as available, from the device’s photo library.
Available in iOS 2.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerSourceTypeCamera
Take a new picture or movie, as available, using the device’s specified, built-in camera. Specify the camera you want by using the cameraDevice
property.
Available in iOS 2.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerSourceTypeSavedPhotosAlbum
Pick an image or movie, as available, from the device’s camera roll. If the device does not have a camera, pick an image or movie, as available, from the Saved Photos folder on the device.
Available in iOS 2.0 and later.
Declared in UIImagePickerController.h
.
A given source may not be available on a given device because the source is not physically present or because it cannot currently be accessed.
Video quality settings for movies recorded with the built-in camera, or transcoded by displaying in the image picker.
enum { UIImagePickerControllerQualityTypeHigh = 0, UIImagePickerControllerQualityType640x480 = 3, UIImagePickerControllerQualityTypeMedium = 1, // default value UIImagePickerControllerQualityTypeLow = 2 }; typedef NSUInteger UIImagePickerControllerQualityType;
UIImagePickerControllerQualityTypeHigh
If recording, specifies that you want to use the highest-quality video recording supported for the active camera on the device.
Recorded files are suitable for on-device playback and for wired transfer to the Desktop using Image Capture; they are likely to be too large for transfer using Wi-Fi.
If displaying a recorded movie in the image picker, specifies that you do not want to reduce the video quality of the movie.
Available in iOS 3.1 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerQualityType640x480
If recording, specifies that you want to use VGA-quality video recording (pixel dimensions of 640x480).
If displaying a recorded movie in the image picker, specifies that you want to transcode higher-quality movies to VGA video quality.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerQualityTypeMedium
If recording, specifies that you want to use medium-quality video recording.
Recorded files can usually be transferred using Wi-Fi. This is the default video quality setting.
If displaying a recorded movie in the image picker, specifies that you want to transcode higher-quality movies to medium video quality.
Available in iOS 3.1 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerQualityTypeLow
If recording, specifies that you want to use low-quality video recording.
Recorded files can usually be transferred over the cellular network.
If displaying a recorded movie in the image picker, specifies that you want to transcode higher-quality movies to low video quality.
Available in iOS 3.1 and later.
Declared in UIImagePickerController.h
.
The constants in this enumeration are for use as values of the videoQuality
property.
The video quality setting applies to transcoding as well as to recording. Specifically, if the video quality setting is lower than the video quality of an existing movie, displaying that movie in the picker results in transcoding the movie to the lower quality.
The camera to use for image or movie capture.
enum { UIImagePickerControllerCameraDeviceRear, UIImagePickerControllerCameraDeviceFront }; typedef NSUInteger UIImagePickerControllerCameraDevice;
UIImagePickerControllerCameraDeviceRear
Specifies the camera on the rear of the device.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerCameraDeviceFront
Specifies the camera on the front of the device.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
The constants in this enumeration are for use as values of the cameraDevice
property.
The category of media for the camera to capture.
enum { UIImagePickerControllerCameraCaptureModePhoto, UIImagePickerControllerCameraCaptureModeVideo }; typedef NSUInteger UIImagePickerControllerCameraCaptureMode;
UIImagePickerControllerCameraCaptureModePhoto
Specifies that the camera captures still images.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerCameraCaptureModeVideo
Specifies that the camera captures movies.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
The constants in this enumeration are for use as values of the cameraCaptureMode
property.
The flash mode to use with the active camera.
enum { UIImagePickerControllerCameraFlashModeOff = -1, UIImagePickerControllerCameraFlashModeAuto = 0, UIImagePickerControllerCameraFlashModeOn = 1 }; typedef NSInteger UIImagePickerControllerCameraFlashMode;
UIImagePickerControllerCameraFlashModeOff
Specifies that flash illumination is always off, no matter what the ambient light conditions are.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerCameraFlashModeAuto
Specifies that the device should consider ambient light conditions to automatically determine whether or not to use flash illumination.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
UIImagePickerControllerCameraFlashModeOn
Specifies that flash illumination is always on, no matter what the ambient light conditions are.
Available in iOS 4.0 and later.
Declared in UIImagePickerController.h
.
The constants in this enumeration are for use as values of the cameraFlashMode
property.
The behavior of the flash depends on the camera capture mode.
For a cameraCaptureMode
value of UIImagePickerControllerCameraCaptureModePhoto
, flash is used to transiently illuminate the subject during still image capture.
For a cameraCaptureMode
value of UIImagePickerControllerCameraCaptureModeVideo
, flash is used to continuously illuminate the subject during movie capture.
For a given camera on a device, flash may or may not be available. You specify the active camera by way of the cameraDevice
property. You can determine if the active camera has flash available by calling the isFlashAvailableForCameraDevice:
class method.
You can manipulate the flash directly to provide effects such as a strobe light. Present a picker interface set to use video capture mode. Then, turn the flash LED on or off by setting the cameraFlashMode
property to UIImagePickerControllerCameraFlashModeOn
or UIImagePickerControllerCameraFlashModeOff
.
Last updated: 2010-06-29