| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/UIKit.framework |
| Availability | Available in iPhone OS 2.0 and later. |
| Declared in | UIImagePickerController.h |
| Related sample code |
The UIImagePickerController class manages the system-supplied user interfaces for choosing and taking pictures and movies on supported devices. Use this class to obtain one of these media types from the user. The class manages user interactions and reports the results of those interactions to the associated delegate object.
By default, the UIImagePickerController class handles all user interactions. All you have to do is tell it which user interface to display, present it, and then dismiss it from your associated delegate object when the user picks an image or movie or cancels the operation. Before presenting this interface, however, always verify that the current device is capable of picking content from the desired source by calling the isSourceTypeAvailable: class method. Also check which media types are available for the source type by calling the availableMediaTypesForSourceType: class method. This latter method allows you to distinguish between a camera that can be used for video recording and one that can be used only for still pictures.
In addition to the default camera interface, in iPhone OS 3.1 and later you can manage the camera interactions yourself, if desired. You can provide a custom overlay view to display a custom picture-taking interface and you can initiate the taking of pictures from your code. 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. After the interface starts, this class notifies your delegate of the user’s actions. Your delegate is then responsible for dismissing the picker and returning to your application’s views. For more information about this protocol, see UIImagePickerControllerDelegate Protocol Reference.
Editing of movies is available when a user picks a saved movie, and involves trimming from the start or end of the movie. Movie capture has a 10 minute duration limit. When a user picks a saved movie, the 10 minute maximum is also enforced; if the picked movie is longer than 10 minutes, the user is forced to trim it before saving.
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. For more information about this class, 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 iPhone OS 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
allowsImageEditing property
delegate property
mediaTypes property
videoQuality property
videoMaximumDuration property
showsCameraControls property
cameraOverlayView property
cameraViewTransform property
– takePicture
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.hA Boolean value indicating whether the user is allowed to edit a selected image. (Deprecated. Use allowsEditing instead.)
@property(nonatomic) BOOL allowsImageEditing
If you allow the user to edit images, the delegate may receive a dictionary with information about the edits that were made.
This property is set to NO by default.
UIImagePickerController.hThe 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.hThe 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.hThe 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.hAn 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 can directly display the still camera or the movie camera, or a selection interface that lets the user choose the picker interface. Before setting this property, check which media types are available by calling the availableMediaTypesForSourceType: class method.
This property is set to the single value kUTTypeImage by default, which designates the still camera picker.
UIImagePickerController.hA Boolean value indicating 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. 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 this property is 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.
UIImagePickerController.hThe 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.
This property is set to UIImagePickerControllerSourceTypePhotoLibrary by default. For a list of possible constants, see “UIImagePickerControllerSourceType.”
UIImagePickerController.hThe maximum duration, in seconds, for a video recording.
@property(nonatomic) NSTimeInterval videoMaximumDuration
The maximum duration for a video recording is 10 minutes. The default value for this property is also 10 minutes.
This property is available only if the mediaTypes property’s value array includes the kUTTypeMovie media type.
UIImagePickerController.hThe video recording quality.
@property(nonatomic) UIImagePickerControllerQualityType videoQuality
Possible values for this property are listed in the “UIImagePickerControllerQualityType” enumeration. The default value is UIImagePickerControllerQualityTypeMedium. To capture a movie using a different video quality, you must set the quality explicitly.
This property is available only if the mediaTypes property’s value array includes the kUTTypeMovie media type.
UIImagePickerController.hReturns 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 iPhone OS 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.hReturns 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.hCaptures 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.hThe source to use when picking an image.
enum {
UIImagePickerControllerSourceTypePhotoLibrary,
UIImagePickerControllerSourceTypeCamera,
UIImagePickerControllerSourceTypeSavedPhotosAlbum
};
typedef NSUInteger UIImagePickerControllerSourceType;
UIImagePickerControllerSourceTypePhotoLibraryPick an image or movie, as available, from the device’s photo library.
Available in iPhone OS 2.0 and later.
Declared in UIImagePickerController.h.
UIImagePickerControllerSourceTypeCameraTake a new picture or movie, as available, using the device’s built-in camera.
Available in iPhone OS 2.0 and later.
Declared in UIImagePickerController.h.
UIImagePickerControllerSourceTypeSavedPhotosAlbumPick 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 iPhone OS 2.0 and later.
Declared in UIImagePickerController.h.
A given source may not always be available on every device. This could be 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.
enum {
UIImagePickerControllerQualityTypeHigh,
UIImagePickerControllerQualityTypeMedium,
UIImagePickerControllerQualityTypeLow
};
typedef NSUInteger UIImagePickerControllerQualityType;
UIImagePickerControllerQualityTypeHighUse high-quality video recording. 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.
Available in iPhone OS 3.1 and later.
Declared in UIImagePickerController.h.
UIImagePickerControllerQualityTypeMediumUse medium-quality video recording. Recorded files can usually be transferred using Wi-Fi. This is the default video quality setting.
Available in iPhone OS 3.1 and later.
Declared in UIImagePickerController.h.
UIImagePickerControllerQualityTypeLowUse low-quality video recording. Recorded files can usually be transferred over the cellular network.
Available in iPhone OS 3.1 and later.
Declared in UIImagePickerController.h.
The constants in this enumeration are for use as values of the videoQuality property.
Last updated: 2009-10-19
iPhone OS Reference Library User Experience: Controls UIImagePickerController Class Reference