ListenableEditorSession

public final class ListenableEditorSession implements EditorSession


ListenableFuture-based compatibility wrapper around EditorSession's suspending methods.

Summary

Public fields

@Nullable Integer

The ID of the background complication or null if there isn't one.

boolean

Whether any changes should be committed when the session is closed (defaults to true).

@NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState>>

A Flow of a Map of complication slot ids to ComplicationSlotState for each complication slot.

@NonNull Instant

The reference preview Instant for this watch face to render previews with.

@NonNull MutableStateFlow<@NonNull UserStyle>

The current UserStyle.

@NonNull UserStyleSchema

The watch face's UserStyleSchema.

@NonNull ComponentName

The ComponentName of the watch face being edited.

@RequiresApi(value = "30") @NonNull WatchFaceId

Unique ID for the instance of the watch face being edited, only defined for Android R and beyond, it's null on Android P and earlier.

Public constructors

Public methods

void
@Nullable Integer
getComplicationSlotIdAt(int x, int y)

Returns the ID of the complication at the given coordinates or null if there isn't one.

@NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationDataSourceInfo>>

Returns a flow of maps of androidx.wear.watchface.ComplicationSlot ids to ComplicationDataSourceInfo that represent the information available about the data source for each complication.

@NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationData>>

Returns a flow of maps of androidx.wear.watchface.ComplicationSlot ids to preview ComplicationData suitable for use in rendering a preview of the watch face.

final @NonNull ListenableFuture<@NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationData>>>

ListenableFuture wrapper around EditorSession.getComplicationsPreviewData.

final @NonNull ListenableFuture<@NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationDataSourceInfo>>>

ListenableFuture wrapper around EditorSession.getComplicationsDataSourceInfo.

final @NonNull ListenableFuture<@NonNull ChosenComplicationDataSource>

ListenableFuture wrapper around EditorSession.openComplicationDataSourceChooser.

@Nullable ChosenComplicationDataSource
openComplicationDataSourceChooser(int complicationSlotId)

Opens the complication data source chooser and returns the chosen complication data source for the specified androidx.wear.watchface.ComplicationSlot.

@NonNull Bitmap
renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    @Nullable Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

Renders the watch face to a Bitmap using the current userStyle.

Public fields

backgroundComplicationSlotId

@Nullable
public @Nullable Integer backgroundComplicationSlotId

The ID of the background complication or null if there isn't one.

commitChangesOnClose

@NonNull
public boolean commitChangesOnClose

Whether any changes should be committed when the session is closed (defaults to true).

Note due to SysUI requirements EditorState can't reliably be sent in the activity result because there are circumstances where ComponentActivity.onStop doesn't get called but the UX requires us to commit changes.

Regardless of the value, on completion of the editor session, the original UserStyle is restored. Note we need SysUI's help to revert any complication data source changes. Caveat some complication data sources have their own config (e.g. the world clock has a timezone setting) and that config currently can't be reverted.

complicationSlotsState

@NonNull
public @NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState>> complicationSlotsState

A Flow of a Map of complication slot ids to ComplicationSlotState for each complication slot.

previewReferenceInstant

@NonNull
public @NonNull Instant previewReferenceInstant

The reference preview Instant for this watch face to render previews with.

userStyle

@NonNull
public @NonNull MutableStateFlow<@NonNull UserStyleuserStyle

The current UserStyle. Assigning to this will cause the style to update. However, styling changes to the watch face will be reverted upon exit.

userStyleSchema

@NonNull
public @NonNull UserStyleSchema userStyleSchema

The watch face's UserStyleSchema.

watchFaceComponentName

@NonNull
public @NonNull ComponentName watchFaceComponentName

The ComponentName of the watch face being edited.

watchFaceId

@RequiresApi(value = "30")
@NonNull
public @RequiresApi(value = "30") @NonNull WatchFaceId watchFaceId

Unique ID for the instance of the watch face being edited, only defined for Android R and beyond, it's null on Android P and earlier. Note each distinct ComponentName can have multiple instances.

Public constructors

ListenableEditorSession

public final ListenableEditorSession(@NonNull EditorSession wrappedEditorSession)

Public methods

close

@NonNull
public void close()

getComplicationSlotIdAt

@Nullable
public Integer getComplicationSlotIdAt(int x, int y)

Returns the ID of the complication at the given coordinates or null if there isn't one. Only androidx.wear.watchface.ComplicationSlots with ComplicationSlotBoundsType.ROUND_RECT are supported by this function.

getComplicationsDataSourceInfo

@NonNull
public StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationDataSourceInfo>> getComplicationsDataSourceInfo()

Returns a flow of maps of androidx.wear.watchface.ComplicationSlot ids to ComplicationDataSourceInfo that represent the information available about the data source for each complication.

A nullComplicationDataSourceInfo will be associated with a complication slot id if the androidx.wear.watchface.ComplicationSlot is configured to show the empty complication data source.

getComplicationsPreviewData

@NonNull
public StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationData>> getComplicationsPreviewData()

Returns a flow of maps of androidx.wear.watchface.ComplicationSlot ids to preview ComplicationData suitable for use in rendering a preview of the watch face. Note if a slot is configured to be empty then it will an instance of EmptyComplicationData. Disabled complicationSlots are included. Note also unlike live data this is static per complication data source, but it may update (on the UiThread) as a result of openComplicationDataSourceChooser.

listenableOpenComplicationDataSourceChooser

@NonNull
public final ListenableFuture<@NonNull ChosenComplicationDataSourcelistenableOpenComplicationDataSourceChooser(int complicationSlotId)

ListenableFuture wrapper around EditorSession.openComplicationDataSourceChooser.

openComplicationDataSourceChooser

@Nullable
public ChosenComplicationDataSource openComplicationDataSourceChooser(int complicationSlotId)

Opens the complication data source chooser and returns the chosen complication data source for the specified androidx.wear.watchface.ComplicationSlot.

The result returns null if the operation was cancelled and otherwise returned an instance of ChosenComplicationDataSource that contains information about the chosen data source.

Parameters
int complicationSlotId

The id of the androidx.wear.watchface.ComplicationSlot to select a complication data source for.

Throws
kotlin.IllegalStateException

if a previous invocation of openComplicationDataSourceChooser is still running when openComplicationDataSourceChooser is called.

renderWatchFaceToBitmap

@NonNull
public Bitmap renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    @Nullable Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

Renders the watch face to a Bitmap using the current userStyle.

Parameters
@NonNull RenderParameters renderParameters

The RenderParameters to render with. Must be DrawMode.INTERACTIVE

@NonNull Instant instant

The Instant to render with

@Nullable Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData

The ComplicationData for each androidx.wear.watchface.ComplicationSlot to render with