public class PickVisualMedia extends ActivityResultContract

java.lang.Object
   ↳ androidx.activity.result.contract.ActivityResultContract
     ↳ androidx.photopicker.activity.PickVisualMedia

An ActivityResultContract to use the Photo Picker to select a single image, video, or other type of visual media.

This contract always prefers the system framework provided Photo Picker available via MediaStore.ACTION_PICK_IMAGES when it is available, but will also provide a fallback on devices that it is not available to provide a consistent API surface across all Android API 19 or higher devices.

The priority order for handling the Photo Picker is:

  1. The system framework provided MediaStore.ACTION_PICK_IMAGES.

The input is a PickVisualMediaRequest.

The output is a Uri when the user has selected a media or null when the user hasn't selected any item. Keep in mind that Uri returned by the photo picker isn't writable.

This can be extended to override createIntent if you wish to pass additional extras to the Intent created by super.createIntent().

Summary

Nested types
public abstract class PickVisualMedia.DefaultTab

Represents filter input type accepted by the photo picker.

DefaultTab object used to open the picker in Albums tab.

DefaultTab object used to open the picker in Photos tab (also the default if no value is provided).

VisualMediaType object used to filter images and video when using the photo picker.

VisualMediaType object used to filter images only when using the photo picker.

Represents the media capabilities of an application.

A builder for constructing MediaCapabilities instances.

VisualMediaType class used to filter a single mime type only when using the photo picker.

VisualMediaType object used to filter video only when using the photo picker.
public sealed interface PickVisualMedia.VisualMediaType

Represents filter input type accepted by the photo picker.

Constants
static final @NonNull String

In cases where the system framework provided MediaStore.ACTION_PICK_IMAGES Photo Picker cannot be implemented, OEMs or system apps can provide a consistent Photo Picker experience to those devices by creating an Activity that handles this action.
static final @NonNull String

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the preferred accent color of the picker.
static final @NonNull String

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES to indicate the predefined album to highlight in the picker.
static final @NonNull String

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the search results to highlight in the picker.
static final @NonNull String

Extra that will be sent by PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates allowing the user to control the order in which images are returned to the calling app.
static final @NonNull String

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the preferred default tab of the picker.
static final @NonNull String

Extra that will be sent by PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates that maximum number of photos the user should select.
static final @NonNull String

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates whether to request location metadata access from the picker.
static final @NonNull String
static final @NonNull String

Key within the EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS bundle specifying the thumbnail aspect ratio.
static final @NonNull String

Bundle key used in system fallback album highlight extras to specify the highlight album.
static final @NonNull String

Bundle key used in system fallback search results highlight extras to specify the text query.
static final @NonNull String

Bundle key used in system fallback highlight extras to specify the value of the highlight type.
static final int

Value for EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO specifying a portrait 9:16 aspect ratio thumbnail sizing within the media grid.
static final int

Value for EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO specifying a square 1:1 aspect ratio thumbnail sizing within the media grid.
static final @NonNull String

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Camera album.
static final @NonNull String

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Downloads album.
static final @NonNull String

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Favorites album.
static final @NonNull String

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Screenshots album.
static final @NonNull String

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Videos album.
static final int

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE specifying a collapsed highlight section.
static final int

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE specifying an expanded highlight grid.

Public constructors

Public methods
@NonNull Intent

Create an intent that can be used for android.app.Activity.startActivityForResult.
final ActivityResultContract.SynchronousResult<Uri>

An optional method you can implement that can be used to potentially provide a result in lieu of starting an activity.
static final boolean

This method is deprecated. This method is deprecated in favor of isPhotoPickerAvailable(context) to support the picker provided by updatable system apps
static final boolean

Check if the current device has support for the photo picker by checking the running Android version, the SDK extension version or the picker provided by a system app implementing ACTION_SYSTEM_FALLBACK_PICK_IMAGES.
final Uri
parseResult(int resultCode, Intent intent)

Convert result obtained from android.app.Activity.onActivityResult to O.

Constants

ACTION_SYSTEM_FALLBACK_PICK_IMAGES

public static final @NonNull String ACTION_SYSTEM_FALLBACK_PICK_IMAGES

In cases where the system framework provided MediaStore.ACTION_PICK_IMAGES Photo Picker cannot be implemented, OEMs or system apps can provide a consistent Photo Picker experience to those devices by creating an Activity that handles this action. This app must also include Intent.CATEGORY_DEFAULT in the activity's intent filter.

Only system apps can implement this action - any non-system apps will be ignored when searching for the activities that handle this Intent.

Note: this should not be used directly, instead relying on the selection logic done by createIntent to create the correct Intent for the current device.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_ACCENT_COLOR

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_ACCENT_COLOR

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the preferred accent color of the picker.

If this extra is not present, the default accent color of the picker will be used.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES to indicate the predefined album to highlight in the picker.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_SEARCH_RESULTS

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_SEARCH_RESULTS

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the search results to highlight in the picker.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_IN_ORDER

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_IN_ORDER

Extra that will be sent by PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates allowing the user to control the order in which images are returned to the calling app.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_LAUNCH_TAB

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_LAUNCH_TAB

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates the preferred default tab of the picker.

If this extra is not present, the default tab of the picker will be used.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_MAX

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_MAX

Extra that will be sent by PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates that maximum number of photos the user should select.

If this extra is not present, only a single photo should be selectable.

If this extra is present but equal to Int.MAX_VALUE, then no limit should be enforced.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_REQUEST_LOCATION_METADATA_ACCESS

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_REQUEST_LOCATION_METADATA_ACCESS

Extra that will be sent by PickVisualMedia and PickMultipleVisualMedia to an Activity that handles ACTION_SYSTEM_FALLBACK_PICK_IMAGES that indicates whether to request location metadata access from the picker.

If this extra is not present, location metadata should be redacted by default.

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS

EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO

public static final @NonNull String EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO

Key within the EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS bundle specifying the thumbnail aspect ratio.

Expected value is an integer: SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_SQUARE_1_1 or SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_PORTRAIT_9_16.

KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID

public static final @NonNull String KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID

Bundle key used in system fallback album highlight extras to specify the highlight album.

KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_SEARCH_TEXT_QUERY

public static final @NonNull String KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_SEARCH_TEXT_QUERY

Bundle key used in system fallback search results highlight extras to specify the text query.

KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE

public static final @NonNull String KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE

Bundle key used in system fallback highlight extras to specify the value of the highlight type.

SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_PORTRAIT_9_16

public static final int SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_PORTRAIT_9_16 = 1

Value for EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO specifying a portrait 9:16 aspect ratio thumbnail sizing within the media grid.

SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_SQUARE_1_1

public static final int SYSTEM_FALLBACK_PICK_IMAGES_ASPECT_RATIO_SQUARE_1_1 = 0

Value for EXTRA_SYSTEM_FALLBACK_PICK_IMAGES_UI_CUSTOMIZATION_PARAMS_ASPECT_RATIO specifying a square 1:1 aspect ratio thumbnail sizing within the media grid.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_CAMERA

public static final @NonNull String SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_CAMERA

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Camera album.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_DOWNLOADS

public static final @NonNull String SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_DOWNLOADS

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Downloads album.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_FAVORITES

public static final @NonNull String SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_FAVORITES

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Favorites album.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_SCREENSHOTS

public static final @NonNull String SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_SCREENSHOTS

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Screenshots album.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_VIDEOS

public static final @NonNull String SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_VIDEOS

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_ALBUM_ID specifying the Videos album.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE_COLLAPSED

public static final int SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE_COLLAPSED = 0

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE specifying a collapsed highlight section.

SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE_EXPANDED

public static final int SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE_EXPANDED = 1

Value for KEY_SYSTEM_FALLBACK_PICK_IMAGES_HIGHLIGHT_TYPE specifying an expanded highlight grid.

Public constructors

PickVisualMedia

Added in 1.0.0-alpha03
public PickVisualMedia()

Public methods

createIntent

Added in 1.0.0-alpha03
@CallSuper
public @NonNull Intent createIntent(
    @NonNull Context context,
    @NonNull PickVisualMediaRequest input
)

Create an intent that can be used for android.app.Activity.startActivityForResult.

getSynchronousResult

Added in 1.0.0-alpha03
public final ActivityResultContract.SynchronousResult<Uri> getSynchronousResult(
    @NonNull Context context,
    @NonNull PickVisualMediaRequest input
)

An optional method you can implement that can be used to potentially provide a result in lieu of starting an activity.

Returns
ActivityResultContract.SynchronousResult<Uri>

the result wrapped in a SynchronousResult or null if the call should proceed to start an activity.

isPhotoPickerAvailable

Added in 1.0.0-alpha03
Deprecated in 1.0.0-alpha03
public static final boolean isPhotoPickerAvailable()

Check if the current device has support for the photo picker by checking the running Android version or the SDK extension version.

Note that this does not check for any Intent handled by ACTION_SYSTEM_FALLBACK_PICK_IMAGES.

isPhotoPickerAvailable

Added in 1.0.0-alpha03
public static final boolean isPhotoPickerAvailable(@NonNull Context context)

Check if the current device has support for the photo picker by checking the running Android version, the SDK extension version or the picker provided by a system app implementing ACTION_SYSTEM_FALLBACK_PICK_IMAGES.

parseResult

Added in 1.0.0-alpha03
public final Uri parseResult(int resultCode, Intent intent)

Convert result obtained from android.app.Activity.onActivityResult to O.