ListenableEditorSession

class ListenableEditorSession : EditorSession


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

Summary

Public companion functions

ListenableEditorSession
@RequiresApi(value = 27)
@UiThread
createHeadlessEditorSession(
    activity: ComponentActivity,
    editIntent: Intent,
    headlessWatchFaceClient: HeadlessWatchFaceClient
)

Constructs an ListenableEditorSession for a remote watch face editor.

ListenableFuture<ListenableEditorSession?>

Constructs a ListenableFuture for a ListenableEditorSession for an on watch face editor.

Public constructors

ListenableEditorSession(wrappedEditorSession: EditorSession)

Public functions

open Unit
open Int?

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

ListenableFuture<ChosenComplicationDataSource?>

ListenableFuture wrapper around EditorSession.openComplicationDataSourceChooser.

open suspend ChosenComplicationDataSource?

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

open Bitmap
renderWatchFaceToBitmap(
    renderParameters: RenderParameters,
    instant: Instant,
    slotIdToComplicationData: Map<IntComplicationData>?
)

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

Public properties

open Int?

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

open Boolean

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

open StateFlow<Map<IntComplicationSlotState>>

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

open StateFlow<Map<IntComplicationDataSourceInfo?>>

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.

open StateFlow<Map<IntComplicationData>>

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.

open Instant

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

open MutableStateFlow<UserStyle>

The current UserStyle.

open UserStyleSchema

The watch face's UserStyleSchema.

open ComponentName

The ComponentName of the watch face being edited.

open WatchFaceId
@RequiresApi(value = 30)
watchFaceId

Unique ID for the instance of the watch face being edited.

Public companion functions

createHeadlessEditorSession

Added in 1.0.0
@RequiresApi(value = 27)
@UiThread
fun createHeadlessEditorSession(
    activity: ComponentActivity,
    editIntent: Intent,
    headlessWatchFaceClient: HeadlessWatchFaceClient
): ListenableEditorSession

Constructs an ListenableEditorSession for a remote watch face editor.

Parameters
activity: ComponentActivity

The ComponentActivity associated with the EditorSession.

editIntent: Intent

Intent sent by SysUI to launch the editing session.

headlessWatchFaceClient: HeadlessWatchFaceClient

The HeadlessWatchFaceClient that backs the constructed EditorSession.

listenableCreateOnWatchEditorSession

Added in 1.0.0
@UiThread
fun listenableCreateOnWatchEditorSession(activity: ComponentActivity): ListenableFuture<ListenableEditorSession?>

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.

Parameters
activity: ComponentActivity

The ComponentActivity associated with the EditorSession.

Public constructors

ListenableEditorSession

Added in 1.0.0
ListenableEditorSession(wrappedEditorSession: EditorSession)

Public functions

close

Added in 1.0.0
open fun close(): Unit

getComplicationSlotIdAt

Added in 1.0.0
open fun getComplicationSlotIdAt(x: Int, y: Int): Int?

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.

listenableOpenComplicationDataSourceChooser

Added in 1.0.0
fun listenableOpenComplicationDataSourceChooser(complicationSlotId: Int): ListenableFuture<ChosenComplicationDataSource?>

ListenableFuture wrapper around EditorSession.openComplicationDataSourceChooser.

openComplicationDataSourceChooser

open suspend fun openComplicationDataSourceChooser(complicationSlotId: Int): ChosenComplicationDataSource?

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
complicationSlotId: Int

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

open fun renderWatchFaceToBitmap(
    renderParameters: RenderParameters,
    instant: Instant,
    slotIdToComplicationData: Map<IntComplicationData>?
): Bitmap

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

Parameters
renderParameters: RenderParameters

The RenderParameters to render with. Must be DrawMode.INTERACTIVE

instant: Instant

The Instant to render with

slotIdToComplicationData: Map<IntComplicationData>?

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

Returns
Bitmap

A Bitmap containing the screen shot with the specified parameters

Public properties

backgroundComplicationSlotId

Added in 1.0.0
open val backgroundComplicationSlotIdInt?

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

commitChangesOnClose

Added in 1.0.0
open var commitChangesOnCloseBoolean

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

Added in 1.0.0
open val complicationSlotsStateStateFlow<Map<IntComplicationSlotState>>

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.

complicationsDataSourceInfo

Added in 1.0.0
open val complicationsDataSourceInfoStateFlow<Map<IntComplicationDataSourceInfo?>>

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.

complicationsPreviewData

Added in 1.0.0
open val complicationsPreviewDataStateFlow<Map<IntComplicationData>>

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.

previewReferenceInstant

Added in 1.0.0
open val previewReferenceInstantInstant

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

userStyle

Added in 1.0.0
open val userStyleMutableStateFlow<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.

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

userStyleSchema

Added in 1.0.0
open val userStyleSchemaUserStyleSchema

The watch face's UserStyleSchema.

watchFaceComponentName

Added in 1.0.0
open val watchFaceComponentNameComponentName

The ComponentName of the watch face being edited.

watchFaceId

Added in 1.0.0
@RequiresApi(value = 30)
open val watchFaceIdWatchFaceId

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.