AbstractEmbeddedPhotoPickerState

@RequiresExtension(extension = 34, version = 15)
@ExperimentalPhotoPickerComposeApi
abstract class AbstractEmbeddedPhotoPickerState : EmbeddedPhotoPickerState

Abstract base class for managing the state of an embedded photo picker.

This class provides common functionalities for handling the picker's lifecycle, UI state (such as expansion and readiness), selected media, and communication with the underlying EmbeddedPhotoPickerProvider. It is designed to be subclassed to provide specific implementations for event handling.

In order to make the state object ready and before calling runSession, the composable that receives this state object should set the surfaceHostToken once the SurfaceView has attached to the window. Additionally, notifyResized should also be called to provide the initial size of the SurfaceView. (This should also be called any time the SurfaceView changes size, see Modifier.onSizeChanged as a modifier that can listen for size changes.)

Key responsibilities include:

This API is experimental, as indicated by ExperimentalPhotoPickerComposeApi, and requires Android U (API level 34, version 15 of the extension), as indicated by RequiresExtension.

Summary

Public companion functions
EmbeddedPhotoPickerClient
@RequiresExtension(extension = 34, version = 15)
createEmbeddedPhotoPickerClient(
    onSessionOpened: (EmbeddedPhotoPickerSession) -> Unit,
    onSessionError: (Throwable) -> Unit,
    onUriPermissionGranted: (List<Uri>) -> Unit,
    onUriPermissionRevoked: (List<Uri>) -> Unit,
    onSelectionComplete: () -> Unit
)

Generates an object which implements EmbeddedPhotoPickerClient that is passed to the EmbeddedPhotoPickerProvider during openSession that will proxy calls that it receives to the relevant provided input callable.

Public constructors

Public functions
final suspend Unit

Request the EmbeddedPhotoPickerSession deselect media items with the provided list of Uris from its interface.
final Unit

Notify the underlying EmbeddedPhotoPickerSession that the current Configuration has changed.
final Unit

Notify the underlying EmbeddedPhotoPickerSession that its parent view has been resized.
abstract Unit

Receiver for when the user is done with their selection and the picker should be collapsed.
abstract Unit

Receiver for when the Photopicker Session encounters a terminal error.
abstract Unit

Receiver for when URI permission has been granted to item(s) selected by the user.
abstract Unit

Receiver for when URI permission has been revoked of an item deselected by the user.
final suspend Unit
runSession(
    provider: EmbeddedPhotoPickerProvider,
    featureInfo: EmbeddedPhotoPickerFeatureInfo,
    onReceiveSession: (EmbeddedPhotoPickerSession) -> Unit
)

Run a EmbeddedPhotoPickerSession using the state provided by this state object.
final Unit

Sets the isExpanded state of the current session.

Public properties
final Int

The ID of the display where the photo picker is shown.
final Boolean

Current expanded state of the photo picker.
final Boolean

Indicates whether the photo picker state is ready to start a session.
final Set<Uri>

A read-only set of URIs representing the currently selected media items.
final IBinder?

The host token for the SurfaceControlViewHost where the picker UI will be rendered.

Inherited functions
From androidx.photopicker.compose.EmbeddedPhotoPickerState
open suspend Unit

Request the EmbeddedPhotoPickerSession deselect the media item with the provided Uri.

Public companion functions

createEmbeddedPhotoPickerClient

@RequiresExtension(extension = 34, version = 15)
fun createEmbeddedPhotoPickerClient(
    onSessionOpened: (EmbeddedPhotoPickerSession) -> Unit,
    onSessionError: (Throwable) -> Unit,
    onUriPermissionGranted: (List<Uri>) -> Unit,
    onUriPermissionRevoked: (List<Uri>) -> Unit,
    onSelectionComplete: () -> Unit
): EmbeddedPhotoPickerClient

Generates an object which implements EmbeddedPhotoPickerClient that is passed to the EmbeddedPhotoPickerProvider during openSession that will proxy calls that it receives to the relevant provided input callable.

Public constructors

AbstractEmbeddedPhotoPickerState

AbstractEmbeddedPhotoPickerState(
    isExpanded: Boolean = false,
    media: Set<Uri> = emptySet<Uri>()
)
Parameters
isExpanded: Boolean = false

Initial expanded state of the photo picker. Defaults to false.
media: Set<Uri> = emptySet<Uri>()

Initial set of selected media URIs. Defaults to an empty set. This set should only include URIs that have been received from the Photopicker. Do not pass general MediaStore URIs here, they will be ignored.

Public functions

deselectUris

final suspend fun deselectUris(uris: List<Uri>): Unit

Request the EmbeddedPhotoPickerSession deselect media items with the provided list of Uris from its interface.

NOTE: The Uri should have been received from the PhotoPicker. Regular MediaStore uris, or other Uris passed here will be ignored by the PhotoPicker.

Parameters
uris: List<Uri>

the List of Uri that should be deselected in the PhotoPicker's interface.

notifyConfigurationChanged

final fun notifyConfigurationChanged(config: Configuration): Unit

Notify the underlying EmbeddedPhotoPickerSession that the current Configuration has changed.

notifyResized

final fun notifyResized(size: IntSize): Unit

Notify the underlying EmbeddedPhotoPickerSession that its parent view has been resized.

Parameters
size: IntSize

The new size of the parent view.

onSelectionComplete

abstract fun onSelectionComplete(): Unit

Receiver for when the user is done with their selection and the picker should be collapsed.

See also
EmbeddedPhotoPickerClient

#onSelectionComplete

onSessionError

abstract fun onSessionError(throwable: Throwable): Unit

Receiver for when the Photopicker Session encounters a terminal error.

See also
EmbeddedPhotoPickerClient

#onSessionError

onUriPermissionGranted

abstract fun onUriPermissionGranted(uris: List<Uri>): Unit

Receiver for when URI permission has been granted to item(s) selected by the user.

See also
EmbeddedPhotoPickerClient

#onUriPermissionGranted

onUriPermissionRevoked

abstract fun onUriPermissionRevoked(uris: List<Uri>): Unit

Receiver for when URI permission has been revoked of an item deselected by the user.

See also
EmbeddedPhotoPickerClient

#onUriPermissionRevoked

runSession

final suspend fun runSession(
    provider: EmbeddedPhotoPickerProvider,
    featureInfo: EmbeddedPhotoPickerFeatureInfo,
    onReceiveSession: (EmbeddedPhotoPickerSession) -> Unit
): Unit

Run a EmbeddedPhotoPickerSession using the state provided by this state object.

This suspended function should be started from a LaunchedEffect in the composable hosting the SurfaceView the EmbeddedPhotoPicker is drawing to. The function should perform the necessary startup logic with the EmbeddedPhotoPickerProvider, and then run the provided client in a child scope of the current CoroutineScope. Throughout the entire session, and then close / cleanup any resources being used when the suspended function is cancelled.

Parameters
provider: EmbeddedPhotoPickerProvider

The provider that should be used for this session.
featureInfo: EmbeddedPhotoPickerFeatureInfo

The client provided EmbeddedPhotoPickerFeatureInfo to configure the Embedded PhotoPicker.
onReceiveSession: (EmbeddedPhotoPickerSession) -> Unit

A callback from the display layer, which can be used to pass the opened Session back to the display layer so it can be attached to the SurfaceView.

setCurrentExpanded

final fun setCurrentExpanded(expanded: Boolean): Unit

Sets the isExpanded state of the current session.

Public properties

displayId

final var displayId: Int

The ID of the display where the photo picker is shown. Set externally before runSession is called.

isExpanded

final var isExpanded: Boolean

Current expanded state of the photo picker. Can be modified using setCurrentExpanded.

isReady

final var isReady: Boolean

Indicates whether the photo picker state is ready to start a session. This becomes true once surface information (host token, display ID, and size) is available.

selectedMedia

final val selectedMedia: Set<Uri>

A read-only set of URIs representing the currently selected media items. Updated internally based on granted/revoked permissions.

surfaceHostToken

final var surfaceHostToken: IBinder?

The host token for the SurfaceControlViewHost where the picker UI will be rendered. Set externally before runSession is called.