EditorSession

interface EditorSession

Known direct subclasses
ListenableEditorSession

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


Interface for manipulating watch face state during a watch face editing session. The editor should adjust userStyle and call openComplicationDataSourceChooser to configure the watch face and call close when done. This reports the updated EditorState to the EditorListeners registered via EditorServiceClient.addListener.

For EditorSessions backed by a headless instance (see createHeadlessEditorSession and EditorRequest.headlessDeviceConfig), style changes are not applied to the interactive instance and it's up to the system to apply them. For EditorSessions backed by an interactive instance style changes are applied immediately. Its possible the system might fail to persist the style changes (e.g. to data base write failure or a crash) and if this happens it's the responsibility of the system to revert the style change.

Summary

Public fields

abstract @Nullable Integer

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

abstract boolean

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

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

Map of complication slot ids to ComplicationSlotState for each complication slot.

abstract @NonNull Instant

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

abstract @NonNull UserStyle

The current UserStyle.

abstract @NonNull UserStyleSchema

The watch face's UserStyleSchema.

abstract @NonNull ComponentName

The ComponentName of the watch face being edited.

abstract @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 methods

abstract @UiThread @Nullable Integer
getComplicationSlotIdAt(@Px int x, @Px int y)

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

abstract @UiThread @NonNull Map<@NonNull Integer, @NonNull ComplicationDataSourceInfo>

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

abstract @UiThread @NonNull Map<@NonNull Integer, @NonNull ComplicationData>

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

abstract @UiThread @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.

abstract @UiThread @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.

Inherited methods

From class AutoCloseable
abstract void

Public fields

backgroundComplicationSlotId

@Nullable
public abstract @Nullable Integer backgroundComplicationSlotId

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

commitChangesOnClose

@NonNull
public abstract 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 abstract @NonNull Map<@NonNull Integer, @NonNull ComplicationSlotStatecomplicationSlotsState

Map of complication slot ids to ComplicationSlotState for each complication slot. Note ComplicationSlotState can change, typically in response to styling.

previewReferenceInstant

@NonNull
public abstract @NonNull Instant previewReferenceInstant

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

userStyle

@NonNull
public abstract @NonNull UserStyle userStyle

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 abstract @NonNull UserStyleSchema userStyleSchema

The watch face's UserStyleSchema.

watchFaceComponentName

@NonNull
public abstract @NonNull ComponentName watchFaceComponentName

The ComponentName of the watch face being edited.

watchFaceId

@NonNull
public abstract @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 methods

getComplicationSlotIdAt

@UiThread
@Nullable
public abstract @UiThread Integer getComplicationSlotIdAt(@Px int x, @Px 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

@UiThread
@NonNull
public abstract @UiThread Map<@NonNull Integer, @NonNull ComplicationDataSourceInfogetComplicationsDataSourceInfo()

Returns a map 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

@UiThread
@NonNull
public abstract @UiThread Map<@NonNull Integer, @NonNull ComplicationDatagetComplicationsPreviewData()

Returns a map 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.

openComplicationDataSourceChooser

@UiThread
@Nullable
public abstract @UiThread 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.

If the complication data source was changed then the map returned by getComplicationsPreviewData is updated (on the UiThread).

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

@UiThread
@NonNull
public abstract @UiThread 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