iOS Developer Library

Developer

UIKit Framework Reference UIImagePickerController Class Reference

Options
Deployment Target:

On This Page
Language:

UIImagePickerController

The UIImagePickerController class manages customizable, system-supplied user interfaces for taking pictures and movies on supported devices, and for choosing saved images and movies for use in your app. An image picker controller manages user interactions and delivers the results of those interactions to a delegate object. More...

Import Statement


import UIKit @import UIKit;

Availability


Available in iOS 2.0 and later.
  • Returns an array of the available media types for the specified source type.

    Declaration

    Swift

    class func availableMediaTypesForSourceType(_ sourceType: UIImagePickerControllerSourceType) -> [AnyObject]?

    Objective-C

    + (NSArray *)availableMediaTypesForSourceType:(UIImagePickerControllerSourceType)sourceType

    Parameters

    sourceType

    The source to use to pick an image.

    Return Value

    An array whose elements identify the available media types for the specified source type.

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns a Boolean value indicating whether the device supports picking media using the specified source type.

    Declaration

    Swift

    class func isSourceTypeAvailable(_ sourceType: UIImagePickerControllerSourceType) -> Bool

    Objective-C

    + (BOOL)isSourceTypeAvailable:(UIImagePickerControllerSourceType)sourceType

    Parameters

    sourceType

    The source to use to pick an image or movie.

    Return Value

    YEStrue if the device supports the specified source type; NOfalse if the specified source type is not available.

    Discussion

    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 NOfalse. Similarly, if the camera is already in use, this method returns NOfalse.

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The type of picker interface to be displayed by the controller.

    Declaration

    Swift

    var sourceType: UIImagePickerControllerSourceType

    Objective-C

    @property(nonatomic) UIImagePickerControllerSourceType sourceType

    Discussion

    Prior to running the picker interface, set this value to the desired source type. The source type you set 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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the user is allowed to edit a selected still image or movie.

    Declaration

    Swift

    var allowsEditing: Bool

    Objective-C

    @property(nonatomic) BOOL allowsEditing

    Discussion

    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 NOfalse by default.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • A Boolean value indicating whether the user is allowed to edit a selected image.

    Deprecation Statement

    Use allowsEditing instead.

    Declaration

    Objective-C

    @property(nonatomic) BOOL allowsImageEditing

    Discussion

    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 NOfalse by default.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 3.1.

  • delegate delegate Property

    The image picker’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: protocol<UIImagePickerControllerDelegate, UINavigationControllerDelegate>?

    Objective-C

    @property(nonatomic, assign) id<UINavigationControllerDelegate, UIImagePickerControllerDelegate> delegate

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • An array indicating the media types to be accessed by the media picker controller.

    Declaration

    Swift

    var mediaTypes: [AnyObject]

    Objective-C

    @property(nonatomic, copy) NSArray *mediaTypes

    Discussion

    Depending on the media types you assign to this property, the picker displays a dedicated interface for still images or movies, 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.

    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.

    When capturing media, the value of this property determines the camera interface to display. When browsing saved media, this property determines the types of media presented in the interface.

    By default, this property is set to the single value kUTTypeImage, which designates the still camera interface when capturing media, and specifies that only still images should be displayed in the media picker when browsing saved media. To designate the movie capture interface, or to indicate that only movies should be displayed when browsing saved media, use the kUTTypeMovie identifier in a statement like this:

    Swift

    • myImagePickerController.mediaTypes = [kUTTypeMovie]

    Objective-C

    • myImagePickerController.mediaTypes =
    • [[NSArray alloc] initWithObjects: (NSString *) kUTTypeMovie, nil];

    To designate all available media types for a source, use a statement like this:

    Swift

    • myImagePickerController.mediaTypes =
    • UIImagePickerController.availableMediaTypesForSourceType(.Camera)

    Objective-C

    • myImagePickerController.mediaTypes =
    • [UIImagePickerController availableMediaTypesForSourceType:
    • UIImagePickerControllerSourceTypeCamera];

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Indicates whether the image picker displays the default camera controls.

    Declaration

    Swift

    var showsCameraControls: Bool

    Objective-C

    @property(nonatomic) BOOL showsCameraControls

    Discussion

    The default value of this property is YEStrue, which specifies that the default camera controls are visible in the picker. Set it to NOfalse to hide the default controls if you want to instead provide a custom overlay view using the cameraOverlayView property.

    If you set this property to NOfalse and provide your own custom controls, you can take multiple pictures before dismissing the image picker interface. However, if you set this property to YEStrue, 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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • The view to display on top of the default image picker interface.

    Declaration

    Swift

    var cameraOverlayView: UIView?

    Objective-C

    @property(nonatomic, retain) UIView *cameraOverlayView

    Discussion

    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.

    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 throwing an NSInvalidArgumentException exception.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • The transform to apply to the camera’s preview image.

    Declaration

    Swift

    var cameraViewTransform: CGAffineTransform

    Objective-C

    @property(nonatomic) CGAffineTransform cameraViewTransform

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • Captures a still image using the camera.

    Declaration

    Swift

    func takePicture()

    Objective-C

    - (void)takePicture

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • Starts video capture using the camera specified by the UIImagePickerControllerCameraDevice property.

    Declaration

    Swift

    func startVideoCapture() -> Bool

    Objective-C

    - (BOOL)startVideoCapture

    Return Value

    YEStrue on success or NOfalse on failure. This method may return a value of NOfalse 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

    Discussion

    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 call 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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • Stops video capture.

    Declaration

    Swift

    func stopVideoCapture()

    Objective-C

    - (void)stopVideoCapture

    Discussion

    After you call this method to stop video capture, the system calls the image picker delegate’s imagePickerController:didFinishPickingMediaWithInfo: method.

    Import Statement

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • The source to use when picking an image or when determining available media types.

    Declaration

    Swift

    enum UIImagePickerControllerSourceType : Int { case PhotoLibrary case Camera case SavedPhotosAlbum }

    Objective-C

    enum { UIImagePickerControllerSourceTypePhotoLibrary, UIImagePickerControllerSourceTypeCamera, UIImagePickerControllerSourceTypeSavedPhotosAlbum }; typedef NSUInteger UIImagePickerControllerSourceType;

    Constants

    • PhotoLibrary

      UIImagePickerControllerSourceTypePhotoLibrary

      Specifies the device’s photo library as the source for the image picker controller.

      Available in iOS 2.0 and later.

    • Camera

      UIImagePickerControllerSourceTypeCamera

      Specifies the device’s built-in camera as the source for the image picker controller. Indicate the specific camera you want (front or rear, as available) by using the cameraDevice property.

      Available in iOS 2.0 and later.

    • SavedPhotosAlbum

      UIImagePickerControllerSourceTypeSavedPhotosAlbum

      Specifies the device’s Camera Roll album as the source for the image picker controller. If the device does not have a camera, specifies the Saved Photos album as the source.

      Available in iOS 2.0 and later.

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Video quality settings for movies recorded with the built-in camera, or transcoded by displaying in the image picker.

    Declaration

    Swift

    enum UIImagePickerControllerQualityType : Int { case TypeHigh case TypeMedium case TypeLow case Type640x480 case TypeIFrame1280x720 case TypeIFrame960x540 }

    Objective-C

    enum { UIImagePickerControllerQualityTypeHigh = 0, UIImagePickerControllerQualityTypeMedium = 1, // default value UIImagePickerControllerQualityTypeLow = 2, UIImagePickerControllerQualityType640x480 = 3, UIImagePickerControllerQualityTypeIFrame1280x720 = 4, UIImagePickerControllerQualityTypeIFrame960x540 = 5 }; typedef NSUInteger UIImagePickerControllerQualityType;

    Constants

    • TypeHigh

      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.

    • Type640x480

      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.

    • TypeMedium

      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.

    • TypeLow

      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.

    • TypeIFrame1280x720

      UIImagePickerControllerQualityTypeIFrame1280x720

      If recording, specifies that you want to use 1280x720 iFrame format.

      The Apple iFrame format supports video editing by keeping content in its native recorded format while editing.

      Available in iOS 5.0 and later.

    • TypeIFrame960x540

      UIImagePickerControllerQualityTypeIFrame960x540

      If recording, specifies that you want to use 960x540 iFrame format.

      The Apple iFrame format supports video editing by keeping content in its native recorded format while editing.

      Available in iOS 5.0 and later.

    Discussion

    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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.1 and later.

  • The camera to use for image or movie capture.

    Declaration

    Swift

    enum UIImagePickerControllerCameraDevice : Int { case Rear case Front }

    Objective-C

    enum { UIImagePickerControllerCameraDeviceRear, UIImagePickerControllerCameraDeviceFront }; typedef NSUInteger UIImagePickerControllerCameraDevice;

    Constants

    • Rear

      UIImagePickerControllerCameraDeviceRear

      Specifies the camera on the rear of the device.

      Available in iOS 4.0 and later.

    • Front

      UIImagePickerControllerCameraDeviceFront

      Specifies the camera on the front of the device.

      Available in iOS 4.0 and later.

    Discussion

    The constants in this enumeration are for use as values of the cameraDevice property.

    Import Statement

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • The category of media for the camera to capture.

    Declaration

    Swift

    enum UIImagePickerControllerCameraCaptureMode : Int { case Photo case Video }

    Objective-C

    enum { UIImagePickerControllerCameraCaptureModePhoto, UIImagePickerControllerCameraCaptureModeVideo }; typedef NSUInteger UIImagePickerControllerCameraCaptureMode;

    Constants

    • Photo

      UIImagePickerControllerCameraCaptureModePhoto

      Specifies that the camera captures still images.

      Available in iOS 4.0 and later.

    • Video

      UIImagePickerControllerCameraCaptureModeVideo

      Specifies that the camera captures movies.

      Available in iOS 4.0 and later.

    Discussion

    The constants in this enumeration are for use as values of the cameraCaptureMode property.

    Import Statement

    import UIKit

    Availability

    Available in iOS 4.0 and later.

  • The flash mode to use with the active camera.

    Declaration

    Swift

    enum UIImagePickerControllerCameraFlashMode : Int { case Off case Auto case On }

    Objective-C

    enum { UIImagePickerControllerCameraFlashModeOff = -1, UIImagePickerControllerCameraFlashModeAuto = 0, UIImagePickerControllerCameraFlashModeOn = 1 }; typedef NSInteger UIImagePickerControllerCameraFlashMode;

    Constants

    • Off

      UIImagePickerControllerCameraFlashModeOff

      Specifies that flash illumination is always off, no matter what the ambient light conditions are.

      Available in iOS 4.0 and later.

    • Auto

      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.

    • On

      UIImagePickerControllerCameraFlashModeOn

      Specifies that flash illumination is always on, no matter what the ambient light conditions are.

      Available in iOS 4.0 and later.

    Discussion

    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 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.

    Import Statement

    import UIKit

    Availability

    Available in iOS 4.0 and later.