ListenableEditorSession

@RequiresApi(value = 27)
@UiThread
public static final @NonNull ListenableEditorSession createHeadlessEditorSession(
    @NonNull ComponentActivity activity,
    @NonNull Intent editIntent,
    @NonNull HeadlessWatchFaceClient headlessWatchFaceClient
)

Constructs an ListenableEditorSession for a remote watch face editor.

public Integer getBackgroundComplicationSlotId()

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

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.

public @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.

public @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.

public @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.

public @NonNull Instant getPreviewReferenceInstant()

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

public @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.

public @NonNull UserStyleSchema getUserStyleSchema()

The watch face's UserStyleSchema.

public @NonNull ComponentName getWatchFaceComponentName()

The ComponentName of the watch face being edited.

@RequiresApi(value = 30)
public @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.

public 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.

@UiThread
public static final @NonNull ListenableFuture<ListenableEditorSession> listenableCreateOnWatchEditorSession(
    @NonNull ComponentActivity activity
)

Constructs a ListenableFuture for a ListenableEditorSession 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.

If watch face editor takes more than 4s to create a watch face, returned future will be resolved with TimeoutCancellationException exception.

public final @NonNull ListenableFuture<ChosenComplicationDataSource> listenableOpenComplicationDataSourceChooser(int complicationSlotId)

ListenableFuture wrapper around EditorSession.openComplicationDataSourceChooser.

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.

public @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.

public 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.

public 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.