public interface EditorSession extends AutoCloseable

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
default static final @NonNull Instant

If passed renderWatchFaceToBitmap this will signal that the watch face's default preview time should be used.
default static final @NonNull Duration

Timeout allowed for waiting for creating the watch face editing session.

Public methods
default static final @NonNull EditorSession
@RequiresApi(value = 27)
@UiThread
createHeadlessEditorSession(
    @NonNull ComponentActivity activity,
    @NonNull Intent editIntent,
    @NonNull HeadlessWatchFaceClient headlessWatchFaceClient
)

Constructs an EditorSession for a remote watch face editor.
default static final @NonNull EditorSession

Constructs an EditorSession for an on watch face editor.
abstract Integer

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

Returns the ID of the complication at the given coordinates or null if there isn't one.
abstract @NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState>>

A Flow of a Map of complication slot ids to ComplicationSlotState for each complication slot.
abstract @NonNull StateFlow<@NonNull Map<@NonNull Integer, 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.
abstract @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.
abstract @NonNull Instant

The reference preview Instant for this watch face to render previews with.
abstract @NonNull MutableStateFlow<@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.
abstract boolean

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

Opens the complication data source chooser and returns the chosen complication data source for the specified androidx.wear.watchface.ComplicationSlot.
abstract @NonNull Bitmap
@UiThread
renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

Renders the watch face to a Bitmap using the current userStyle.
abstract void
@UiThread
setCommitChangesOnClose(boolean commitChangesOnClose)

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

For the duration of the editor session, applies an override to complications rendered via renderWatchFaceToBitmap.

Inherited methods
From java.lang.AutoCloseable
abstract void

Public fields

DEFAULT_PREVIEW_INSTANT

default static final @NonNull Instant DEFAULT_PREVIEW_INSTANT

If passed renderWatchFaceToBitmap this will signal that the watch face's default preview time should be used.

EDITING_SESSION_TIMEOUT

default static final @NonNull Duration EDITING_SESSION_TIMEOUT

Timeout allowed for waiting for creating the watch face editing session.

Public methods

createHeadlessEditorSession

Added in 1.0.0
@RequiresApi(value = 27)
@UiThread
default static final @NonNull EditorSession createHeadlessEditorSession(
    @NonNull ComponentActivity activity,
    @NonNull Intent editIntent,
    @NonNull HeadlessWatchFaceClient headlessWatchFaceClient
)

Constructs an EditorSession for a remote watch face editor.

Caution the remote watchface must have been built with the same version of the watch face libraries.

Parameters
@NonNull ComponentActivity activity

The ComponentActivity associated with the EditorSession.
@NonNull Intent editIntent

The Intent sent by SysUI to launch the editing session.
@NonNull HeadlessWatchFaceClient headlessWatchFaceClient

The HeadlessWatchFaceClient to use for rendering etc...
Returns
@NonNull EditorSession

The EditorSession or null if it could not be constructed.

createOnWatchEditorSession

@UiThread
default static final @NonNull EditorSession createOnWatchEditorSession(@NonNull ComponentActivity activity)

Constructs an EditorSession for an on watch face editor. This registers an activity result handler and so it must be called during an Activity or Fragment initialization path. The EditorSession is lifecycle aware and will automatically close when onDestroy is received.

Parameters
@NonNull ComponentActivity activity

The ComponentActivity associated with the EditorSession.
Returns
@NonNull EditorSession

Deferred which is resolved with either the EditorSession or null if it can't be constructed.
Throws
kotlinx.coroutines.TimeoutCancellationException

if it takes longer than EDITING_SESSION_TIMEOUT to create a watch face editor.

getBackgroundComplicationSlotId

Added in 1.0.0
abstract Integer getBackgroundComplicationSlotId()

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

getComplicationSlotIdAt

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

getComplicationSlotsState

Added in 1.0.0
abstract @NonNull StateFlow<@NonNull Map<@NonNull Integer, @NonNull ComplicationSlotState>> getComplicationSlotsState()

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

If accessed from java, consider using androidx.lifecycle.FlowLiveDataConversions.asLiveData to observe changes.

getComplicationsDataSourceInfo

Added in 1.0.0
abstract @NonNull StateFlow<@NonNull Map<@NonNull Integer, 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. This data is fetched asynchronously and the map will initially be empty. For watch faces without complications this will always be empty.

Note new data may be pushed as result of running openComplicationDataSourceChooser.

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

getComplicationsPreviewData

Added in 1.0.0
abstract @NonNull 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. This data is fetched asynchronously and the map will initially be empty. For watch faces without complications this will always be empty.

Note new data may be pushed as a result of running openComplicationDataSourceChooser.

Note if a slot is configured to be empty then the map will contain an instance of EmptyComplicationData for that slot. Disabled complicationSlots are included in the map.

If accessed from java, consider using androidx.lifecycle.FlowLiveDataConversions.asLiveData to observe changes.

getPreviewReferenceInstant

Added in 1.0.0
abstract @NonNull Instant getPreviewReferenceInstant()

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

getUserStyle

Added in 1.0.0
abstract @NonNull MutableStateFlow<@NonNull UserStyle> getUserStyle()

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

If accessed from java, consider using androidx.lifecycle.FlowLiveDataConversions.asLiveData to observe changes.

getUserStyleSchema

Added in 1.0.0
abstract @NonNull UserStyleSchema getUserStyleSchema()

The watch face's UserStyleSchema.

getWatchFaceComponentName

Added in 1.0.0
abstract @NonNull ComponentName getWatchFaceComponentName()

The ComponentName of the watch face being edited.

getWatchFaceId

Added in 1.0.0
abstract @NonNull WatchFaceId getWatchFaceId()

Unique ID for the instance of the watch face being edited. Note each distinct ComponentName can sometimes have multiple instances. See WatchFaceId for more details.

isCommitChangesOnClose

Added in 1.0.0
@UiThread
abstract boolean isCommitChangesOnClose()

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.

openComplicationDataSourceChooser

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

@UiThread
abstract @NonNull Bitmap renderWatchFaceToBitmap(
    @NonNull RenderParameters renderParameters,
    @NonNull Instant instant,
    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
Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData

Override ComplicationData for each androidx.wear.watchface.ComplicationSlot to render with. Note using this feature is somewhat computationally expensive because under the hood it saves and restores the backing watch face instance's complications. If you need to render multiple times with the same slotIdToComplicationData, consider using renderWatchFaceToBitmap for a more efficient alternative.
Returns
@NonNull Bitmap

A Bitmap containing the screen shot with the specified parameters

setCommitChangesOnClose

Added in 1.0.0
@UiThread
abstract void setCommitChangesOnClose(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.

setOverrideComplications

default void setOverrideComplications(
    @NonNull Map<@NonNull Integer, @NonNull ComplicationData> slotIdToComplicationData
)

For the duration of the editor session, applies an override to complications rendered via renderWatchFaceToBitmap. If you need to render multiple times with the same slotIdToComplicationData it's more efficient to use this API and call renderWatchFaceToBitmap with null slotIdToComplicationData. When the editor session ends this override will be removed.

Note if after this call updated complications are sent via InteractiveWatchFaceClient.updateComplicationData, they will only be applied once the editor session has ended.

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

The complications you wish to set. Any slots not covered by this map will be unchanged.