StatefulWatchFaceService


public abstract class StatefulWatchFaceService<Extra extends Object> extends WatchFaceService


WatchFaceService is required to be stateless as multiple can be created in parallel. StatefulWatchFaceService allows for metadata to be associated with watch faces on a per instance basis. This state is created by createExtra and is passed into other methods.

Summary

Public constructors

<Extra extends Object> StatefulWatchFaceService()

Protected methods

final @NonNull ComplicationSlotsManager

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty ComplicationSlotsManager.

@NonNull ComplicationSlotsManager
@WorkerThread
createComplicationSlotsManager(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty ComplicationSlotsManager.

abstract @NonNull Extra

Constructs the user defined Extra object which is passed as a parameter to the other methods.

final @NonNull UserStyleFlavors
createUserStyleFlavors(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull ComplicationSlotsManager complicationSlotsManager
)

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create non-empty UserStyleFlavors.

@NonNull UserStyleFlavors
@WorkerThread
createUserStyleFlavors(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull Extra extra
)

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create non-empty UserStyleFlavors.

final @NonNull UserStyleSchema

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty UserStyleSchema.

@NonNull UserStyleSchema

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty UserStyleSchema.

final @NonNull WatchFace
createWatchFace(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull WatchState watchState,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository
)

Override this factory method to create your WatchFaceImpl.

abstract @NonNull WatchFace
@WorkerThread
createWatchFace(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull WatchState watchState,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

Override this factory method to create your WatchFaceImpl.

final @NonNull ComplicationSlotInflationFactory

Used when inflating ComplicationSlots from XML (i.e the manifest contains androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata) to provide a ComplicationSlotInflationFactory which provides the CanvasComplicationFactory and where necessary edge complication ComplicationTapFilters needed for inflating ComplicationSlots.

@NonNull ComplicationSlotInflationFactory
@WorkerThread
getComplicationSlotInflationFactory(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

Used when inflating ComplicationSlots from XML (i.e the manifest contains androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata) to provide a ComplicationSlotInflationFactory which provides the CanvasComplicationFactory and where necessary edge complication ComplicationTapFilters needed for inflating ComplicationSlots.

Inherited methods

From android.content.Context
boolean
final int
getColor(int p0)
final @NonNull ColorStateList
final @Nullable Drawable
getDrawable(int p0)
final @NonNull String
getString(int p0)
final @NonNull String
getString(int p0, @NonNull Object p1)
final @NonNull T
<T extends Object> getSystemService(@NonNull Class<@NonNull T> p0)
final @NonNull CharSequence
getText(int p0)
final @NonNull TypedArray
final @NonNull TypedArray
final @NonNull TypedArray
obtainStyledAttributes(int p0, @NonNull int[] p1)
final @NonNull TypedArray
obtainStyledAttributes(
    @Nullable AttributeSet p0,
    @NonNull int[] p1,
    int p2,
    int p3
)
void
void
sendBroadcastWithMultiplePermissions(
    @NonNull Intent p0,
    @NonNull String[] p1
)
From android.content.ContextWrapper
boolean
bindIsolatedService(
    @NonNull Intent p0,
    int p1,
    @NonNull String p2,
    @NonNull Executor p3,
    @NonNull ServiceConnection p4
)
boolean
boolean
boolean
boolean
bindService(
    @NonNull Intent p0,
    int p1,
    @NonNull Executor p2,
    @NonNull ServiceConnection p3
)
boolean
boolean
bindServiceAsUser(
    @NonNull Intent p0,
    @NonNull ServiceConnection p1,
    int p2,
    @NonNull UserHandle p3
)
int
int
@NonNull int[]
int
int
@NonNull int[]
int
checkPermission(@NonNull String p0, int p1, int p2)
int
int
checkUriPermission(@NonNull Uri p0, int p1, int p2, int p3)
int
checkUriPermission(
    @Nullable Uri p0,
    @Nullable String p1,
    @Nullable String p2,
    int p3,
    int p4,
    int p5
)
@NonNull int[]
checkUriPermissions(@NonNull List<@NonNull Uri> p0, int p1, int p2, int p3)
void

This method is deprecated. Deprecated in Java

@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull Context
@NonNull String[]
boolean
boolean
boolean
void
void
enforceCallingOrSelfUriPermission(
    @NonNull Uri p0,
    int p1,
    @NonNull String p2
)
void
void
void
enforcePermission(@NonNull String p0, int p1, int p2, @Nullable String p3)
void
enforceUriPermission(
    @NonNull Uri p0,
    int p1,
    int p2,
    int p3,
    @NonNull String p4
)
void
enforceUriPermission(
    @Nullable Uri p0,
    @Nullable String p1,
    @Nullable String p2,
    int p3,
    int p4,
    int p5,
    @Nullable String p6
)
@NonNull String[]
@NonNull Context
@NonNull ApplicationInfo
@NonNull AssetManager
@NonNull AttributionSource
@Nullable String
@NonNull Context
@NonNull File
@NonNull ClassLoader
@NonNull File
@NonNull ContentResolver
@NonNull File
@NonNull File
int
@NonNull File
getDir(@NonNull String p0, int p1)
@Nullable Display
@Nullable File
@NonNull File[]
@Nullable File
@NonNull File[]
@NonNull File[]
@NonNull File
@NonNull File
@NonNull Executor
@NonNull Looper
@NonNull File
@NonNull File
@NonNull File[]
@NonNull String
@NonNull String
@NonNull PackageManager
@NonNull String
@NonNull String
@Nullable ContextParams
@NonNull Resources
@NonNull SharedPreferences
@NonNull Object
String
@NonNull Resources.Theme
@NonNull Drawable

This method is deprecated. Deprecated in Java

int

This method is deprecated. Deprecated in Java

int

This method is deprecated. Deprecated in Java

void
boolean
boolean
boolean
boolean
boolean
@NonNull FileInputStream
@NonNull FileOutputStream
openFileOutput(@NonNull String p0, int p1)
@NonNull SQLiteDatabase
openOrCreateDatabase(
    @NonNull String p0,
    int p1,
    @NonNull SQLiteDatabase.CursorFactory p2
)
@NonNull SQLiteDatabase
@NonNull Drawable

This method is deprecated. Deprecated in Java

void
void
Intent
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    int p2
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    @Nullable String p2,
    @Nullable Handler p3
)
Intent
registerReceiver(
    @Nullable BroadcastReceiver p0,
    @NonNull IntentFilter p1,
    @Nullable String p2,
    @Nullable Handler p3,
    int p4
)
void

This method is deprecated. Deprecated in Java

void

This method is deprecated. Deprecated in Java

void
void
void
void
void
void
void
void
void
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable Bundle p2
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable BroadcastReceiver p2,
    @Nullable Handler p3,
    int p4,
    @Nullable String p5,
    @Nullable Bundle p6
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable Bundle p2,
    @Nullable BroadcastReceiver p3,
    @Nullable Handler p4,
    int p5,
    @Nullable String p6,
    @Nullable Bundle p7
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable String p1,
    @Nullable String p2,
    @Nullable BroadcastReceiver p3,
    @Nullable Handler p4,
    int p5,
    @Nullable String p6,
    @Nullable Bundle p7
)
void
sendOrderedBroadcast(
    @NonNull Intent p0,
    int p1,
    @Nullable String p2,
    @Nullable String p3,
    @Nullable BroadcastReceiver p4,
    @Nullable Handler p5,
    @Nullable String p6,
    @Nullable Bundle p7,
    @Nullable Bundle p8
)
void
sendOrderedBroadcastAsUser(
    @NonNull Intent p0,
    @NonNull UserHandle p1,
    @Nullable String p2,
    @Nullable BroadcastReceiver p3,
    @Nullable Handler p4,
    int p5,
    @Nullable String p6,
    @Nullable Bundle p7
)
void

This method is deprecated. Deprecated in Java

void

This method is deprecated. Deprecated in Java

void

This method is deprecated. Deprecated in Java

void
sendStickyOrderedBroadcast(
    @NonNull Intent p0,
    @Nullable BroadcastReceiver p1,
    @Nullable Handler p2,
    int p3,
    @Nullable String p4,
    @Nullable Bundle p5
)

This method is deprecated. Deprecated in Java

void
sendStickyOrderedBroadcastAsUser(
    @NonNull Intent p0,
    @NonNull UserHandle p1,
    @Nullable BroadcastReceiver p2,
    @Nullable Handler p3,
    int p4,
    @Nullable String p5,
    @Nullable Bundle p6
)

This method is deprecated. Deprecated in Java

void
setTheme(int p0)
void

This method is deprecated. Deprecated in Java

void

This method is deprecated. Deprecated in Java

void
startActivities(@NonNull Intent[] p0)
void
startActivities(@NonNull Intent[] p0, @Nullable Bundle p1)
void
void
@Nullable ComponentName
boolean
startInstrumentation(
    @NonNull ComponentName p0,
    @Nullable String p1,
    @Nullable Bundle p2
)
void
startIntentSender(
    @NonNull IntentSender p0,
    @Nullable Intent p1,
    int p2,
    int p3,
    int p4
)
void
startIntentSender(
    @NonNull IntentSender p0,
    @Nullable Intent p1,
    int p2,
    int p3,
    int p4,
    @Nullable Bundle p5
)
@Nullable ComponentName
boolean
void
void
void
void
void
updateServiceGroup(@NonNull ServiceConnection p0, int p1, int p2)
From android.app.Service
void
final @NonNull Application
final int
void
void
void
onStart(@NonNull Intent p0, int p1)

This method is deprecated. Deprecated in Java

int
onStartCommand(@NonNull Intent p0, int p1, int p2)
void
void
onTimeout(int p0)
void
onTrimMemory(int p0)
boolean
final void
final void
startForeground(int p0, @NonNull Notification p1, int p2)
final void
stopForeground(boolean p0)

This method is deprecated. Deprecated in Java

final void
final void
final void
stopSelf(int p0)
final boolean
From android.service.wallpaper.WallpaperService
final IBinder
void
void
From androidx.wear.watchface.WatchFaceService
void
@UiThread
dump(
    @NonNull FileDescriptor fd,
    @NonNull PrintWriter writer,
    @NonNull String[] args
)
final @NonNull Handler

Returns the lazily constructed background thread Handler.

ComplicationSlotInflationFactory

This method is deprecated. Use the version with currentUserStyleRepository argument instead

final @NonNull Handler

Returns the ui thread Handler.

void
final @NonNull WallpaperService.Engine

Creates an interactive engine for WallpaperService.

Public constructors

StatefulWatchFaceService

public <Extra extends Object> StatefulWatchFaceService()

Protected methods

createComplicationSlotsManager

Added in 1.3.0-alpha04
protected final @NonNull ComplicationSlotsManager createComplicationSlotsManager(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository
)

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty ComplicationSlotsManager. This manager will be passed to createUserStyleFlavors and createWatchFace. This will be called from a background thread but the ComplicationSlotsManager should be accessed exclusively from the UiThread afterwards.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

createComplicationSlotsManager

Added in 1.3.0-alpha04
@WorkerThread
protected @NonNull ComplicationSlotsManager createComplicationSlotsManager(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty ComplicationSlotsManager. This manager will be passed to createUserStyleFlavors and createWatchFace. This will be called from a background thread but the ComplicationSlotsManager should be accessed exclusively from the UiThread afterwards.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

@NonNull Extra extra

The object returned by createExtra.

createExtra

Added in 1.3.0-alpha04
protected abstract @NonNull Extra createExtra()

Constructs the user defined Extra object which is passed as a parameter to the other methods.

createUserStyleFlavors

Added in 1.3.0-alpha04
protected final @NonNull UserStyleFlavors createUserStyleFlavors(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull ComplicationSlotsManager complicationSlotsManager
)

If the WatchFaceService's manifest doesn't define a androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create non-empty UserStyleFlavors. This is called on a background thread. The system reads the flavors once and changes may be ignored until the APK is updated. Metadata tag "androidx.wear.watchface.FLAVORS_SUPPORTED" should be added to let the system know the service supports flavors.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

@NonNull ComplicationSlotsManager complicationSlotsManager

The ComplicationSlotsManager returned by createComplicationSlotsManager

Returns
@NonNull UserStyleFlavors

The UserStyleFlavors, which is exposed to the system.

createUserStyleFlavors

Added in 1.3.0-alpha04
@WorkerThread
protected @NonNull UserStyleFlavors createUserStyleFlavors(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull Extra extra
)

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create non-empty UserStyleFlavors. This is called on a background thread. The system reads the flavors once and changes may be ignored until the APK is updated. Metadata tag "androidx.wear.watchface.FLAVORS_SUPPORTED" should be added to let the system know the service supports flavors.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

@NonNull ComplicationSlotsManager complicationSlotsManager

The ComplicationSlotsManager returned by createComplicationSlotsManager

@NonNull Extra extra

The object returned by createExtra.

Returns
@NonNull UserStyleFlavors

The UserStyleFlavors, which is exposed to the system.

createUserStyleSchema

Added in 1.3.0-alpha04
protected final @NonNull UserStyleSchema createUserStyleSchema()

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty UserStyleSchema. A CurrentUserStyleRepository constructed with this schema will be passed to createComplicationSlotsManager, createUserStyleFlavors and createWatchFace. This is called on a background thread.

createUserStyleSchema

Added in 1.3.0-alpha04
@WorkerThread
protected @NonNull UserStyleSchema createUserStyleSchema(@NonNull Extra extra)

If the WatchFaceService's manifest doesn't define an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition meta data tag then override this factory method to create a non-empty UserStyleSchema. A CurrentUserStyleRepository constructed with this schema will be passed to createComplicationSlotsManager, createUserStyleFlavors and createWatchFace. This is called on a background thread.

Parameters
@NonNull Extra extra

The object returned by createExtra.

createWatchFace

protected final @NonNull WatchFace createWatchFace(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull WatchState watchState,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository
)

Override this factory method to create your WatchFaceImpl. This method will be called by the library on a background thread, if possible any expensive initialization should be done asynchronously. The WatchFace and its Renderer should be accessed exclusively from the UiThread afterwards. There is a memory barrier between construction and rendering so no special threading primitives are required.

Warning the system will likely time out waiting for watch face initialization if it takes longer than MAX_CREATE_WATCHFACE_TIME_MILLIS milliseconds.

Parameters
@NonNull SurfaceHolder surfaceHolder

The SurfaceHolder to pass to the Renderer's constructor.

@NonNull WatchState watchState

The WatchState for the watch face.

@NonNull ComplicationSlotsManager complicationSlotsManager

The ComplicationSlotsManager returned by createComplicationSlotsManager.

@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

Returns
@NonNull WatchFace

A WatchFace whose Renderer uses the provided surfaceHolder.

createWatchFace

@WorkerThread
protected abstract @NonNull WatchFace createWatchFace(
    @NonNull SurfaceHolder surfaceHolder,
    @NonNull WatchState watchState,
    @NonNull ComplicationSlotsManager complicationSlotsManager,
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

Override this factory method to create your WatchFaceImpl. This method will be called by the library on a background thread, if possible any expensive initialization should be done asynchronously. The WatchFace and its Renderer should be accessed exclusively from the UiThread afterwards. There is a memory barrier between construction and rendering so no special threading primitives are required.

Warning the system will likely time out waiting for watch face initialization if it takes longer than WatchFaceService.MAX_CREATE_WATCHFACE_TIME_MILLIS milliseconds.

Parameters
@NonNull SurfaceHolder surfaceHolder

The SurfaceHolder to pass to the Renderer's constructor.

@NonNull WatchState watchState

The WatchState for the watch face.

@NonNull ComplicationSlotsManager complicationSlotsManager

The ComplicationSlotsManager returned by createComplicationSlotsManager.

@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

@NonNull Extra extra

The object returned by createExtra.

Returns
@NonNull WatchFace

A WatchFace whose Renderer uses the provided surfaceHolder.

getComplicationSlotInflationFactory

Added in 1.3.0-alpha04
protected final @NonNull ComplicationSlotInflationFactory getComplicationSlotInflationFactory(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository
)

Used when inflating ComplicationSlots from XML (i.e the manifest contains androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata) to provide a ComplicationSlotInflationFactory which provides the CanvasComplicationFactory and where necessary edge complication ComplicationTapFilters needed for inflating ComplicationSlots.

If an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata tag is defined for your WatchFaceService 's manifest, and your XML includes tags then you must override this method. A NotImplementedError exception will be thrown if you don't.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

getComplicationSlotInflationFactory

Added in 1.3.0-alpha04
@WorkerThread
protected @NonNull ComplicationSlotInflationFactory getComplicationSlotInflationFactory(
    @NonNull CurrentUserStyleRepository currentUserStyleRepository,
    @NonNull Extra extra
)

Used when inflating ComplicationSlots from XML (i.e the manifest contains androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata) to provide a ComplicationSlotInflationFactory which provides the CanvasComplicationFactory and where necessary edge complication ComplicationTapFilters needed for inflating ComplicationSlots.

If an androidx.wear.watchface.XmlSchemaAndComplicationSlotsDefinition metadata tag is defined for your WatchFaceService 's manifest, and your XML includes tags then you must override this method. A NotImplementedError exception will be thrown if you don't.

Parameters
@NonNull CurrentUserStyleRepository currentUserStyleRepository

The CurrentUserStyleRepository constructed using the UserStyleSchema returned by createUserStyleSchema.

@NonNull Extra extra

The object returned by createExtra.