Wear Watchface

Declaring dependencies

To add a dependency on Wear, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

dependencies {
    // Use to implement wear watchfaces
    implementation "androidx.wear.watchface:watchface:1.2.1"

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation "androidx.wear.watchface:watchface-editor:1.2.1"

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

dependencies {
    // Use to implement wear watchfaces
    implementation("androidx.wear.watchface:watchface:1.2.1")

    // Use to implement wear watchface complications
    implementation "androidx.wear.watchface:watchface-complications-data-source:1.2.1"
    // (Kotlin-specific extensions)
    implementation "androidx.wear.watchface:watchface-complications-data-source-ktx:1.2.1"

    // Use to implement a watchface style and complication editor
    implementation("androidx.wear.watchface:watchface-editor:1.2.1")

    // Can use to render complications.
    // This library is optional and watchfaces may have custom implementation for rendering
    // complications.
    implementation "androidx.wear.watchface:watchface-complications-rendering:1.2.1"
}

For more information about dependencies, see Add build dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.3

Version 1.3.0-alpha07

April 23, 2025

androidx.wear.watchface:watchface-*:1.3.0-alpha07 is released. Version 1.3.0-alpha07 contains these commits.

New Features

• It’s been possible to define a watch face’s UserStyle schema for a while, and it’s possible to define ColorUserStyleSetting in XML.

API Changes

• Projects released with Kotlin 2.0 require KGP 2.0.0 or newer to be consumed. (Idb6b5)
• Added the Watch Face Push API which allows a Wear OS app to install a watch face on a watch programmatically.

Bug Fixes

• Complication providers using 1.3.0-alpha06 are encouraged to upgrade because a crash bug with ComplicationDataSourceUpdateRequester on the next version of WearOS has been fixed.

Version 1.3.0-alpha06

March 26, 2025

androidx.wear.watchface:watchface-*:1.3.0-alpha06 is released. Version 1.3.0-alpha06 contains these commits.

New Features

• The wear watchface APIs (watchface, watchface-client, watchface-client-guava, watchface-complications-rendering, watchface-data, watchface-editor, watchface-editor-guava, and watchface-style) have been depreciated in favor of the Wear Watchface Format, and will eventually be removed from AndroidX. The complication APIs are not deprecated and will remain. (Ice960)
• The complication APIs are now able to communicate with WearSDK directly, which is more efficient due to fewer IPC hops.

Version 1.3.0-alpha05

January 15, 2025

androidx.wear.watchface:watchface-*:1.3.0-alpha05 is released. Version 1.3.0-alpha05 contains these commits.

New Features

Watch faces commonly allow the user to select colors using a ListUserStyle. While this works, it entails sending the icons over bluetooth to the companion editor which is inefficient, so we’ve introduced ColorUserStyleSetting where the payload is a list of one or more color per style which has a significantly more compact wire format.

We’ve added an OEM facing feature which allows OEM complication providers to add extras to ComplicationData for use by OEM watch faces.

API Changes

• UserStyleSetting and UserStyleOption classes now have builders which is the recommended way to construct them. (Iacd03)
• Support for passing extras in ComplicationData. This is intended for use by OEMs where they control both the complication provider and the receiving watch face. Setting an extra requires the privileged com.google.android.wearable.permission.COMPLICATION_EXTRAS permission. (I4e3b2)
• Watch faces commonly allow the user to select colors using a ListUserStyle, with an icon for each ListOption. Since UserStyle schemas are sent over bluetooth, it is important to keep the size of the schema down which can be a problem if many dozens of color options are given due to all those icons. To help with this we've added ColorUserStyleSetting where the option contains a list of colors instead of an icon, which is much more compact. (Ib542e)
• ColorUserStyleSetting and ColorOption require API 34 for use. (I8771d)

Bug Fixes

• This library now uses JSpecify nullness annotations, which are type-use. Kotlin developers should use the following compiler argument to enforce correct usage: -Xjspecify-annotations=strict (this is the default starting with version 2.1.0 of the Kotlin compiler). (Ifd363, b/326456246)

Version 1.3.0-alpha04

September 18, 2024

androidx.wear.watchface:watchface-*:1.3.0-alpha04 is released. Version 1.3.0-alpha04 contains these commits.

New Features

• Added support for lazy loading of icons in UserStyleSettings and UserStyleOptions which is a performance win for loading watch faces. (Iaf43d)
• Added an option for an updated screenshot to be taken whenever the system configuration changes (e.g. if the locale changed) via the new Watchface.setUpdateScreenshotOnConfigurationChange. By default this setting is off. (I765a1)

Bug Fixes

• Removed manual outlining of access to new platform APIs since this happens automatically via API modeling when using R8 with AGP 7.3 or later (e.g. R8 version 3.3) and for all builds when using AGP 8.1 or later (e.g. D8 version 8.1). Clients who are not using AGP are advised to update to D8 version 8.1 or later. See this article for more details. (Ia60e0, b/345472586)

Version 1.3.0-alpha03

April 17, 2024

androidx.wear.watchface:watchface-*:1.3.0-alpha03 is released. Version 1.3.0-alpha03 contains these commits.

API Changes

• We've added EditorSession#setOverrideComplications which temporarily sets the underlying watchface instance's ComplicationData while editing. If complications change infrequently, this is more efficient than passing overrides in via EditorSession#renderWatchFaceToBitmap. (I19384)

Bug Fixes

• Previously selectComplicationDataForInstant was calling toApiComplicationData for any timelines, meaning the subsequent === reference equality test would always fail. This meant complications were getting reloaded every frame leading to battery drain. (717406)

Version 1.3.0-alpha02

April 3, 2024

androidx.wear.watchface:watchface-*:1.3.0-alpha02 is released. Version 1.3.0-alpha02 contains these commits.

New Features

• We now use reference equality to compare best and selectedData because the equals operator is expensive. (446b00)

API Changes

• We’ve added a no-fallback dynamic API for GoalProgressComplicationData. (c33264)

Version 1.3.0-alpha01

February 7, 2024

androidx.wear.watchface:watchface-*:1.3.0-alpha01 is released. Version 1.3.0-alpha01 contains these commits.

New Features

• WatchFaceServices can be initialized concurrently and as such they should be stateless, to support this we’ve added StatefulWatchFaceService in which a user defined extra created by createExtra() is passed into all the overrides called during initialization.
• GlesRenderer2 now has a constructor overload which lets you specify a list of attributes to try in turn with eglChooseConfig.

API Changes

• StatefulWatchFaceService now supports an override of getComplicationSlotInflationFactory into which the user-defined extra created by createExtra() is passed. (I82d9f)
• Some watch faces need to share auxiliary data created during createUserStyleSchema with the other initialisation methods. Because there wasn't a better alternative, developers typically made their WatchFaceServices stateful. This is dangerous because multiple instances can be created concurrently which can lead to bugs. To resolve this we've introduced StatefulWatchFaceService and StatefulWatchFaceRuntimeService where a user defined type is created by createExtra() and is passed to the various create methods as a parameter. (If8a99)
• We've added getUserStyleFlavors to InteractiveWatchFaceClient, which is of interest primarily for OEMs. (I0f5d8)
• GlesRenderer2 now has a constructor overload which lets you specify a list of attributes to try in turn with eglChooseConfig. This for example allows you to first try a config with anti-aliasing and to fallback to one without if needed. (I1ba74)
• From Android U, support for SystemDataSources.DATA_SOURCE_HEART_RATE will be added to WearOS. This complication is only guaranteed to support SHORT_TEXT complications, but it's recommended for the ComplicationSlot to accept SMALL_IMAGE too because OEMs may choose to serve a shortcut to their health app instead of the live value. (I34223)
• We've added METADATA_KEY_CONFIG_RESTORE_SUPPORTED which from Android U onwards, controls what happens when the system is restored from a backup for complication data source with METADATA_KEY_DATA_SOURCE_CONFIG_ACTION. By default the system assumes that the complication data source service supports backup of any configuration data, but if it does not then it can add metadata setting METADATA_KEY_DATA_SOURCE_CONFIG_ACTION to false which will mark the complication slot as not configured. (I6c505)

Version 1.2

Version 1.2.1

January 24, 2024

androidx.wear.watchface:watchface-*:1.2.1 is released. Version 1.2.1 contains these commits.

Bug Fixes

• Fixed a crash on Samsung Galaxy Watch 4, 5 & 6. (43f0b0)

Version 1.2.0

November 29, 2023

androidx.wear.watchface:watchface-*:1.2.0 is released. Version 1.2.0 contains these commits.

Important changes since 1.1.0

• We’ve added support some new complication types which are available for use from Android T:
  • GoalProgressComplicationData which is similar to RangedValueComplicationData except it's for progress towards a goal where min implicitly is zero, and the value is allowed to be larger than targetValue.
  • WeightedElementsComplicationData which consists of an array of Elements (pairs of weight and color) along with optional text/title/image. These might be displayed as a pie chart where the colors need to be meaningful given the context, since there typically isn't room in a complication to render labels.
• We’ve added support for optional ColorRanges to RangedValueComplicationData. Normally complications would be rendered in colors of the watch face's choosing, but sometimes the ComplicationDataSource is best placed to set the colors e.g. when they have a particular semantic meaning. E.g. red to blue for temperature.
• Almost every type of ComplicationData now supports SmallImages.
• We've added ComplicationDisplayPolicy where DO_NOT_SHOW_WHEN_DEVICE_LOCKED instructs a compatible watch face to not display the complication when the device is locked.
• From Android T, OEMs will be able to determine if a complication request is from a watch face in the list defined by the android.support.wearable.complications.SAFE_WATCH_FACES metadata in their provider’s manifest by ComplicationRequest#isForSafeWatchFace. The provider will need the com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE permission to receive anything other than TargetWatchFaceSafety.UNKNOWN`.
• UserStyleFlavors has become a non-experimental feature.

Version 1.2.0-rc01

October 18, 2023

androidx.wear.watchface:watchface-*:1.2.0-rc01 is released. Version 1.2.0-rc01 contains these commits.

Version 1.2.0-beta02

September 6, 2023

androidx.wear.watchface:watchface-*:1.2.0-beta02 is released. Version 1.2.0-beta02 contains these commits.

New Features

• SuspendingComplicationDataSourceService#onDestroy is now open. Please note support for a system default weather complication has been removed.

API Changes

• Revert "Expose a new data source for weather complications". (I6f335)

Version 1.2.0-beta01

August 23, 2023

androidx.wear.watchface:watchface-*:1.2.0-beta01 is released. Version 1.2.0-beta01 contains these commits.

New Features

• From Android T, WearOS will now support a default weather system complication.

API Changes

• Add weather default system fallback for complications. (Ia0994)
• This patch adds WatchFaceRuntimeService and WatchFaceControlClient.createWatchFaceRuntimeControlClient along with guava wrappers. These add support for watch face runtimes which are a special kind of watch face that loads it's definition from another package. Currently WearOS only supports the runtime for the Android Watch Face Format. (I2799f)
• This patch is a follow up to aosp/2636578 where we rename the int defs so any code depending on WatchFaceType, CanvasType, TapType or ComplicationsSlotBoundsType doesn't need to change. (I4098b)
• Updated API files to annotate compatibility suppression. (I8e87a, b/287516207)
• This patch exposes WatchFaceType constants in WatchFaceTypes, CanvasType constants in CanvasTypes, TapType constants in TapTypes and ComplicationsSlotBoundsType constants in ComplicationsSlotBoundsType. (I3b85a, b/288750666)
• WatchFace.OverlayStyle has very low usage and is not well supported by OEMs so we're depreciating it with intention to remove it at a later date. (I7344a)

Version 1.2.0-alpha09

June 21, 2023

androidx.wear.watchface:watchface-*:1.2.0-alpha09 is released. Version 1.2.0-alpha09 contains these commits.

New Features

• RangedValueComplicationData.Builder now accepts DynamicFloat, and a new DynamicComplicationText is available as a subclass of ComplicationText, both of which can utilize dynamic expressions as well as platform bindings that are updated at 1hz on supported Wear 4 devices.

API Changes

• Added dynamic types for daily distance, daily calories and daily floors. Keys for platform health sources are now under PlatformHealthSources.Keys (Ib7637)
• Implement PlatformDataProvider to provide heart rate and daily steps. SensorGateway interface is removed from public API. (I55b84)
• Rename StateEntryValue to DynamicDataValue, and update the state APIs to use the DynamicDataKey. (If1c01)
• Add AppDataKey for accessing app pushed state; Add PlatformDataKey for accessing platform data; Add namespace support in StateStore. (I7985e)
• enable/disablePlatformSource methods have been removed from DynamicTypeEvaluator. The caller should be responsible for updates. (I78c6d)
• Allow capping the size of bound data types. (Ie2966)

Version 1.2.0-alpha08

April 19, 2023

androidx.wear.watchface:watchface-*:1.2.0-alpha08 is released. Version 1.2.0-alpha08 contains these commits.

New Features

• From Android T, complication providers with the privileged com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE may register androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES metadata which overrides android.support.wearable.complications.SUPPORTED_TYPES for safe watch faces. This means a complication provider may choose to serve different types to trusted vs untrusted watchfaces.

API Changes

• Propagation of @Deprecated class to property (I882d1, b/271441831)
• Value parameter name for Enum.valueOf changed (Ia9b89)
• More thrown exceptions from enum valueOf (I818fe)
• We've removed renderWatchFaceToSurface in favour of createRemoteWatchFaceView which is built on top of SurfaceControlViewHost and allows the caller to embed a view from the watch face, which is rendered when the client calls RemoteWatchFaceViewHost#renderWatchFace. (Ib311d)
• We've added renderWatchFaceToSurface to InteractiveWatchFaceClient, HeadlessWatchFaceClient and EditorSession. Typically this will be more performant than rendering to a bitmap. (Ieacad)
• ObservableStateStore has been rename to StateStore. (Ieb0e2)
• Added DynamicTypeEvaluator.Builder instead of constructor arguments to allow more optional arguments, including ObservableStateStore which now defaults to an empty store. (I6f832)
• Refactored order of parameters in DynamicTypeEvaluator. (Ic1ba4)
• Executor has been added to the DynamicTypeEvaluator.bind methods. (I346ab)
• We have added startEvaluation method to the BoundDynamicType to trigger the evaluation after dynamic type is bound. (I19908)
• Complication providers with the privileged com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE may register androidx.wear.watchface.complications.datasource.SAFE_WATCH_FACE_SUPPORTED_TYPES metadata which overrides android.support.wearable.complications.SUPPORTED_TYPES for safe watch faces. (Id1c73)
• We've renamed CustomValueUserStyleSettings2 to LargeCustomValueUserStyleSettings. (Ic17ac)

Bug Fixes

• DynamicTypeValueReceiver#onPreUpdate has been removed. (I2dc35)

Version 1.2.0-alpha07

February 22, 2023

androidx.wear.watchface:watchface-*:1.2.0-alpha07 is released. Version 1.2.0-alpha07 contains these commits.

New Features

• From Android T, OEMs will be able to determine if a complication request is from a watch face in the list defined by the android.support.wearable.complications.SAFE_WATCH_FACES metadata in their provider’s manifest by ComplicationRequest#isForSafeWatchFace. The provider will need the com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE permission to receive anything other than TargetWatchFaceSafety.UNKNOWN.

• Also from Android T CustomValueUserStyleSetting2 is available for use which can hold up to 12.5kb. The previous limit for CustomValueUserStyleSetting was 1kb. Despite the increased size limits, watch face developers are encouraged to keep the data small because the settings get sent over bluetooth during editing and bluetooth bandwidth is limited.

API Changes

• We've added an optional parameter eglContextAttribList to GlesRenderer & GlesRenderer2 which allows you to set the EGL14.EGL_CONTEXT_CLIENT_VERSION passed to EGL14.eglCreateContext. (I2a83e)
• We've migrated watch face libs over to androidx.core.util.Consumer instead of java.util.function.Consumer. (I273f5)
• More thrown exceptions from KT property accessors (Iff9d9)
• We've added InteractiveWatchFaceClient.isComplicationDisplayPolicySupported so that the client can determine if it has to emulate support or not on behalf of old watch faces. (I24c89)
• We've decided that isForSafeWatchFace should be a tri-state IntDef. (Ief2f7)
• For android T we've introduced ComplicationRequest.isForSafeWatchFace which is intended for OEM use and it requires com.google.wear.permission.GET_IS_FOR_SAFE_WATCH_FACE. For data sources in the system image, this will return true if the requesting watch face is inside the list of safe watchfaces specified by the data source in it's manifest. (I0cbb6)
• For android T we've added CustomValueUserStyleSetting2 which can hold up to 12.5kb. The previous limit for CustomValueUserStyleSetting was 1kb. (I0b100)

Version 1.2.0-alpha06

January 25, 2023

androidx.wear.watchface:watchface-*:1.2.0-alpha06 is released. Version 1.2.0-alpha06 contains these commits.

New Features

• Work is ongoing to add support for complication platform bindings, this isn’t ready for use yet, but stay tuned!
• We’ve added XML ComplicationSlot support for the new complication types, GOAL_PROGRESS and WEIGHTED_ELEMENTS.

Bug Fixes

• Fixes a leak where the watch face editor was not properly released on Samsung devices. (3b5987)
• Fixes a bug where sometimes the complications didn’t display properly when switching between a watch face with multiple favorites. (b38ece)
• Fixes a serialization bug with perOptionScreenReaderNames that lead to watch face crashes. (e9f466)

Version 1.2.0-alpha05

December 7, 2022

androidx.wear.watchface:watchface-*:1.2.0-alpha05 is released. Version 1.2.0-alpha05 contains these commits.

New Features

• A while back we added support for hierarchical UserStyleSettings, and from android T it’s now possible to have more than one ComplicationSlotsUserStyleSetting in a hierarchy. Only one ComplicationSlotsUserStyleSetting will be active, based on the user’s style selections.

• We’re improving screen reader support for ListOption and ComplicationSlotsOption by adding a screenReaderName field, note prior to android T this field will be ignored by companion editors.

API Changes

• We've added a new optional screenReaderName field to ListOption and ComplicationSlotsOption for use by editors - will be ignored by companion editors on devices before android T. (I75326)
• From android T multiple ComplicationSlotsUserStyleSettings are now supported in a style hierarchy as long as at most only one of them can be active at any one time. We've added a utility function findComplicationSlotsOptionForUserStyle to UserStyleSchema to help find the active ComplicationSlotsOption if any. (Ic2b06)
• RangedValuesTypes have been pulled into RangedValueComplicationData's companion object and renamed to TYPE_UNDEFINED, TYPE_RATING and a new TYPE_PERCENTAGE has been added. (I55d02)
• We've renamed experimental DynamicFloat to FloatExpression and marked it as @hide. (Idf4f1)
• Adding @JvmDefaultWithCompatibility annotation (I8f206)

Version 1.2.0-alpha04

November 9, 2022

androidx.wear.watchface:watchface-*:1.2.0-alpha04 is released. Version 1.2.0-alpha04 contains these commits.

New Features

• For Android T we’ve added support for two new complication types, GoalProgressComplicationData and WeightedElementsComplicationData.
• GoalProgressComplicationData is similar to RangedValueComplicationData but it’s value is allowed to go past the target (for RangedValueComplicationData the value is clamped to the range [min .. max]) which has implications for visual design that might not suit all watch faces.
• GoalProgressComplicationData adds support for pie charts and similar breakdowns of simple data.
• We’ve added optional support for ColorRamps to RangedValueComplicationData.
• For Android T, We've added ComplicationPersistencePolicy and setCachePolicy to ComplicationData which currently allows a provider to control whether a complication is persisted or not (i.e. whether it's cached past reboot). Most complications won't need to set cache control, but doing so can fix corner cases with stale data for some complications that update frequently (e.g. health data complications). We've also added ComplicationDisplayPolicy where DO_NOT_SHOW_WHEN_DEVICE_LOCKED instructs a compatible watch face to not display the complication when the device is locked. (Ic9574)

API Changes

• GoalProgressComplicationData, WeightedElementsComplicationData and ColorRamp are no longer experimental. (Ica9e2)
• ComplicationPersistencePolicy and ComplicationDisplayPolicy are now properly marked as T APIs. (I31d88)
• The deprecated ComplicationSlotOverlay constructor now has DeprecationLevel.WARNING allowing it to be called from java once again. (Ib308c)
• We've fixed some java compat issues with ComplicationRequestListener, CanvasComplication, ComplicationTapFilter and InteractiveWatchFaceClient by annotating them with @JvmDefaultWithCompatibility (Id94fc)
• We've removed experimental ProtoLayoutComplicationData and ListComplicationData. The developer story for these was unclear, we hope to revisit in future. (I9df05)
• We've added a ValueType back to RangedValueComplicationData. WeightedElementsComplicationData now supports a background color. We've removed DiscreteRangedValueComplicationData because it's functionality is a subset of WeightedElementsComplicationData. (I6446c)

Bug Fixes

• Include the isForScreenShot in the equals and hash code. Make sure the onRenderParametersChanged gets a correct isForScreenshot value (I04a41)
• Fixed leaks of WatchFaceControlService from headless clients. (e90e00)

Version 1.2.0-alpha03

October 5, 2022

androidx.wear.watchface:watchface-*:1.2.0-alpha03 is released. Version 1.2.0-alpha03 contains these commits.

New Features

• No new features, but we have fixed a couple of watch face editor bugs.

API Changes

• Deprecated UserStyleSchema.userStyleSettings as rootUserStyleSettings become non-experimental (Ie96e3)
• Move rootUserStyleSettings out of experimental (I8d6b3)
• We've marked WatchFaceColors as experimental because it is not supported by all systems (I6d75d)
• Expose DisconnectReasons in the public API to make it work withIntDef. (I791f8)

Bug Fixes

• Close any open on watch editor if SysUI dies. If SysUI dies and the on watch face editor doesn't close, the watch face could be left in an inconsistent state because the system relies on SysUI to persist any user style changes.(ba762a
• Fix a memory leak in ComplicationDataSourceInfoRetriever, where a kotlin coroutine continuation was acting as a gc root and retaining the editor activity.(33ee06)

Version 1.2.0-alpha02

September 21, 2022

androidx.wear.watchface:watchface-*:1.2.0-alpha02 is released. Version 1.2.0-alpha02 contains these commits.

New Features

• Some watch faces have configuration outside of the UserStyle that affects it visually, (e.g. selecting a background photo). We’ve added Renderer.sendPreviewImageNeedsUpdateRequest which allows the watch face to request an updated preview image. Note this requires a corresponding system up date to work.

• We’ve also added an API for watch faces to expose their colors to the system which may choose its color palette based on this. Note that this has been made experimental in a follow on patch.

• Just about every type of ComplicationData now supports SmallImages.

API Changes

• Wallpaper manager can sometimes detach from an engine and make another. We've added a DisconnectReason int def and extended ClientDisconnectListener with a new method which includes a DisconnectReason, allowing the listener to observe engine detaches. (I45cce)
• Added two optional parameters nameResourceId and screenReaderResourceId to ComplicationSlotOverlay constructor (I157e8)
• We've added a guava wrapper for the new overload of getOrCreateInteractiveWatchFaceClient with a PreviewImageUpdateRequestedListener. (Ic31f0)
• We've added Renderer.sendPreviewImageNeedsUpdateRequest which is useful for watch faces that have state outside of the UserStyleSchema which affects the way they look (e.g. a watch face with a selectable background image). On the client side we've added PreviewImageUpdateRequestedListener as an optional parameter to getOrCreateInteractiveWatchFaceClient to observe these requests. (Iff44a)
• We've simplified the API for exposing WatchFaceColors, now there's a simple property called watchFaceColors on the Renderer which the watch face can set, this should be updated as necessary in response to any style changes. Instead of using WallpaperManager to observe color changes, we've added OnWatchFaceColorsListener to InteractiveWatchFaceClient. (I490bc)
• We've added a WatchFaceColors class which holds the three most prominent watch face colors and added open methods watchfaceColors & notifyWatchFaceColorsChanged to the Renderer, these allow the system to obtain the colors of the watch face via WallpaperManager.getWallpaperColors. (I3d611)
• ShortTextComplicationData, RangedValueComplicationData, NoPermissionComplicationData (and experimental DiscreteRangedValueComplicationData, GoalProgressComplicationData and WeightedElementsComplicationData) now all support SmallImages. If a watch face chooses to render a complication with multiple colors, it now has the option to use a multi-colored SmallImage where previously it would have had to use a monochromatic image. (I257df)
• Refactor PreviewImageUpdateRequestedListener to be a Consumer<> instead (Ia875d)
• Replace custom Single Abstract Method (SAM) type OnWatchfaceColorsListener with generic Java SAM type (Consumer) (I0c489)
• We've deprecated the old getOrCreateInteractiveWatchFaceClient and listenableGetOrCreateInteractiveWatchFaceClient methods that don't specify a PreviewImageUpdateRequestedListener. (Iec502)

Bug Fixes

• DisconnectReason.BINDER_DIED has been renamed to DisconnectReason.ENGINE_DIED. (I4eb0e)

Version 1.2.0-alpha01

August 10, 2022

androidx.wear.watchface:watchface-*:1.2.0-alpha01 is released. Version 1.2.0-alpha01 contains these commits.

New Features

• We’ve added experimental support for various new complication formats. This is an area of active development; these new formats are subject to change without notice and currently there’s no renderer support from CanvasComplicationDrawable.
• We’ve also added optional margins to complication slots which make small complications easier to tap on.

API Changes

• The experimental BoundingArc class is now immutable. (If624a)
• Small complications can be tricky to tap on. To help mitigate this, we've introduced support for margins which increase the tappable area without affecting rendering. Unless specified (either in code or via XML) ComplciationSlots have zero sized margins. (I14089)
• Changed getComplicationSlotInflationFactory(CurrentUserStyleRepository) signature to return a non-null factory instance. It was an error to return null before, so this is just making the API contract clearer. (I0fcc0)
• We've added currentUserStyleRepository argument to the WatchFaceService.getComplicationSlotInflationFactory method to be consistent with createComplicationSlotsManager. (I2ddd2)
• UserStyleFlavors have become non-experimental feature. (I69cdc)
• We have removed the experimental ValueType from RangedValueComplicationData and instead introduced experimental DiscreteRangedValueComplicationData which is like RangedValueComplicationData except for integer range & value. We've also introduced experimental GoalProgressComplicationData which is similar to RangedValueComplicationData except it's for progress towards a goal where min implicitly is zero, and the value is allowed to be larger than targetValue. Note for all RangedValue variants at least one of monochromeImage, text or title must be specified. (I9590c)
• We removed boundsWithMargins from ComplicationSlotState because system software doesn't have a use case for it. (I42e26)
• We've added experimental support for WeightedElementsComplicationData which consists of an array of Elements (pairs of weight and color) along with optional text/title/image. These might be displayed as a pie chart where the colors need to be meaningful given the context, since there typically isn't room in a complication to render labels. (I87eea)
• The experimental ColorRamps optionally used by RangedValueComplicationData and GoalProgressComplicationData now allow you to specify a sequence of up to seven colors and a flag stating whether the colors should be smoothly tweened or whether equal sized solid steps of color should be rendered. (I9f5bf)
• RangedValueComplicationData.drawSegmented has been changed to valueType which is an int with a corresponding ValueType IntDef which provides semantic meaning to the ranged value and may be used by the complication renderer to influence styling. (I0616b)
• We've added experimental support for optional ColorRanges to RangedValueComplicationData. Normally complications would be rendered in colors of the watch face's choosing, but sometimes the ComplicationDataSource is best placed to set the colors e.g. when they have a particular semantic meaning. E.g. red to blue for temperature. (I5153a)
• We've added an experimental drawSegmented hint to RangedValueComplicationData. This signals renderers to draw the ranged value indicator with segments, where 1 segment = 1 unit. (I7d7c1)

Bug Fixes

• We've added the ability to define ComplicationSlotBounds relative to a predefined screen coordinate system. (I0985d)

Version 1.1

Version 1.1.1

August 10, 2022

androidx.wear.watchface:watchface-*:1.1.1 is released. Version 1.1.1 contains these commits.

• This is a bug fix release and users of version 1.1.0 are strongly encouraged to upgrade.

Bug Fixes

• Watch face initialization is asynchronous and if a complication is received before the watch face is ready it gets put on the pendingInitialComplications list and is applied later. Unfortunately pendingInitialComplications was applied too soon which meant there was a window of time during watch face initialization where complications would still get put on pendingInitialComplications and be ignored. This has now been fixed. In addition This patch fixes a bug where ComplicationRenderer was wrongly trying to load placeholders asynchronously, which failed leading to the compilation graphic never updating. Finally this patch fixes a hopefully theoretical bug where multiple pendingInitialComplications need to be merged. (0d03ba3)

• Fix potential deadlock in InteractiveInstanceManager where getExistingInstanceOrSetPendingWallpaperInteractiveWatchFaceInstance was holding the lock longer than necessary. Usually we'd expect engine.setUserStyle to be quick but if for some reason it's not then we could end up with a deadlock/ANR. This patch moves unnecessary work out of the lock, removing the potential for a deadlock.(5a2adca)

• Fix several issues that retained WatchFaceService. The WakeLock can sometimes retain the WatchFaceService, adding a release() call fixes this. Also the StateFlows can retain WatchFaceService, canceling the underlying CoroutineScopes fixes that.(fd48138)

• Add timeouts to awaitDeferredWatchFace* and fix watchfaceOverlayStyle NullPointerException. In normal circumstances this shouldn't timeout including after fresh install and DirectBoot scenarios where the CPU load is high. We've also fixed a NPE if getWatchfaceOverlayStyle is called after close().(a4c3a5a)

Version 1.1.0

June 15, 2022

androidx.wear.watchface:watchface-*:1.1.0 is released. Version 1.1.0 contains these commits.

Important changes since 1.0.0

Improved Editing:

• We added support for hierarchical schemas, which allows a hierarchy of styles to be scribed by editor UIs. You can now specify separate icons for use by on watch face and companion editors.
• There is opt-in support for multiple instances of a watch face, each instance has a unique ID available across all API surfaces.
• You can now specify human readable names for ComplicationSlots for use in editors.
• Experimental support for styling “flavors”, a curated selection of styles which will be visible from the companion editor.
• When editing two instances of the watchface are loaded, it’s now possible for watchface instances to share resources, saving memory
• When picking a complication in the on watch face editor, the current provider is now preselected.

Improved Complications:

• You can now specify the ComplicationType for the primary and secondary data sources, giving developers more flexibility for the out of box experience.
• We added ComplicationDataTimeline which provides a sequence of time-gated data to be delivered to the watch face which can be cached and updated automatically. For example, today's weather forecast at various times or multiple upcoming calendar events.
• The ComponentName of the complication provider is part of the ComplicationData.
• Complications are now cached which provides a better experience when switching between watch faces.

Other changes:

• The UserStyleSchema and ComplicationSlots can now be defined in XML. This simplifies watch face construction and allows for faster metadata queries from the system.
• Watch faces can now influence the colors used for rendering the system overlay.

Version 1.1.0-rc01

May 18, 2022

androidx.wear.watchface:watchface-*:1.1.0-rc01 is released. Version 1.1.0-rc01 contains these commits.

New Features

• We’ve made some usability tweaks to watchface XML support, making it easier to specify ComplicationSlotBounds and supporting references. Experimentation with edge complication BoundingArc continues, plumbing it through to drawHighlight although it’s not recommended for use at that time.

API Changes

• We've added an experimental overload of drawHighlight which accepts a BoundingArc parameter. (I705f8)
• Watch face XML now supports resource references. It lets you use the same constants both in XML and your code. (I3ef61)
• We've added the ability to define ComplicationSlotBounds in center_x, center_y, size_x, size_y form. Now it is also possible to use different units (i.e. dp) using resource references. (Iace98)

Bug Fixes

• Fix runBlockingWithTracing which was running tasks on the wrong context.(4f595fe)
• Make BaseEditorSession.close synchronous. The problem with BaseEditorSession.close being asynchronous is that we release the ComplicationDataSourceInfoRetriever too late leading to warning spam in logcat. This was probably harmless but logcat spam is distracting and should be avoided.(35a5308)

Version 1.1.0-beta02

May 11, 2022

androidx.wear.watchface:watchface-*:1.1.0-beta02 is released. Version 1.1.0-beta02 contains these commits.

New Features

• We’ve added experimental support for new ComplicationData types, these are not yet ready for use but watch this space.

API Changes

• We've added BoundingArc, an experimental class that describes the geometry of an edge complication slot. This has been added to ComplicationSlot and plumbed through to ComplicationSlotState and WatchFaceMetadataClient. (I61a40)
• We've added the ability to inherit settings in UserStyleSetting XML. It lets you reduce verbosity and share a setting between watchfaces. (Ief841)
• We have added two new experimental types of ComplicationData: ListComplicationData & ProtoLayoutComplicationData. Currently there's no rendering support for either of these types and WearOS doesn't currently recognize these types if added to a ComplicationDataSource's manifest. (I1811c)

Bug Fixes

• Fix serialization of TimeLineEntry type. We were not serializing the TimeLineEntry type which meant cached TimeLineEntries of type NoData would be incorrectly interpreted as having the parent complication's type leading to NPEs when non-existent required fields were accessed. (55ffdf5)
• Fix a bug where setComplicationData dropped timeline fields(fb392f5)
• Fixes a bug where very occasionally runBlockingWithTracing would lead to an NPE(12ca62e)
• Fixes a bug where we sometimes get ClassNotFoundException: android.support.wearable.complications.ComplicationText when receiving a complication.(217942d9)
• Fixes a bug in GlesRenderer.backgroundThreadInitInternal where it was only calling onBackgroundThreadGlContextCreated if EGL14.eglCreateContext was called. Fixes another bug where there was a visual glitch in the screenshot caused by verticalFlip.(c674ad2)
• Fix WatchFaceService XML version check, it was loading from the wrong package.(dfa06f3)
• Placeholder wire format now uses an inner bundle. We don't want placeholders to break existing watchfaces which might use the hidden inner a.s.w.c.ComplicationData. Previously the wire format of a NoDataComplication data stored the placeholder in the usual fields (problematic because old watch faces would render the placeholder string which isn't intended), instead we now use an inner bundle to fully isolate this.(d5e7bd2)

Version 1.1.0-beta01

April 20, 2022

androidx.wear.watchface:watchface-*:1.1.0-beta01 is released. Version 1.1.0-beta01 contains these commits.

API Changes

• Now WatchFaceMetadataClient methods (getUserStyleSchema, getComplicationSlotMetadataMap, getUserStyleFlavors) and HeadlessWatchFaceClient.getUserStyleFlavors throw unchecked RuntimeException instead of WatchFaceException. (I0718a)
• WatchFaceMetadataClient.WatchFaceException has been moved out of the class to allow it to be reused. (I4e869)

Bug Fixes

• WatchFaceMetadataClient will no longer crash when sent partial ComplicationSlotBounds.(Iaafd)

Version 1.1.0-alpha05

April 6, 2022

androidx.wear.watchface:watchface-*:1.1.0-alpha05 is released. Version 1.1.0-alpha05 contains these commits.

New Features

• You can now tell which data source sent a ComplicationData by inspecting ComplicationData.dataSource, some watch faces may use this to customize complication display. (I44a73)

API Changes

• Renderer.CanvasRenderer and Renderer.GlesRenderer have been deprecated in favor of Renderer.CanvasRenderer2 and Renderer.GlesRenderer2 which support SharedAssets which are passed to the render methods. For java interop we've introduced ListenableCanvasRenderer2 and ListenableGlesRenderer2. (I31ffa)
• Added @WatchFaceFlavorsExperimental ability to define flavors - preconfigured list of styled watchfaces (I04dd0)
• Renderer.sharedAssets is now a StateFlow and we've removed the unused Renderer.SharedAssetsFactory (I12ac5)
• UserStyleSchema.userStyleSettings is not deprecated anymore (Iba7e3)
• We've added HeadlessWatchFaceClient.getUserStyleSchemaDigestHash which allows a HeadlessWatchFaceClient to avoid the relatively low overhead of passing the schema over AIDL before computing the digest hash. (I33597)
• We've added isUserStyleSchemaStatic to WatchFaceMetadataClient which is true if and only if the UserStyleSchema can be relied on not to change unless the watch face APK is updated. (I45a3f)
• We have added getDigestHash to UserStyleSchema which computes a digest hash of the schema. This can be used to efficiently determine if the UserStyleSchema has changed. (I2063d)
• METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIGURATION_SUPPORTED renamed to METADATA_KEY_DATA_SOURCE_DEFAULT_CONFIG_SUPPORTED (I9ba5d)
• UserStyleSetting.OnWatchEditorData has been renamed to UserStyleSetting.WatchFaceEditorData, it contains data that's used purely by the on watch face editor. (If3afb)

Version 1.1.0-alpha04

March 9, 2022

androidx.wear.watchface:watchface-*:1.1.0-alpha04 is released. Version 1.1.0-alpha04 contains these commits.

API Changes

• Up to date ComplicationData may not always be available (e.g. expired cached ComplicationData) so we've extended NoDataComplication with an optional placeholder ComplicationData and added ComplicationText.PLACEHOLDER, MonochromaticImage.PLACEHOLDER, SmallImage.PLACEHOLDER, PhotoImage.PLACEHOLDER which are only allowed to be used inside the context of a NoDataComplicationData placeholder. If selected these placeholders are suggested to be rendered with gray boxes/arcs. (I6285d)
• We've added ComplicationData.getNextChangeInstant which tells you the next Instant after the reference Instant at which any field of the complication may change. This is used internally to schedule frames for complication updates. E.g. if a watch face normally updates once per minute, setting the stop watch complication will cause it to update once per second. (I7ceb2)
• EditorSession.watchFaceId can now be used on all API levels. In addition its value will now always be consistent with WatchState.watchFaceInstanceId. (I323b9)
• The getPendingIntentForTouchEvent API is no longer necessary since the underlying issue has been fixed in the framework, so all the related APIs have been removed. Watchfaces do not need to do anything special for PendingIntents to fire, even if the home button has recently been pressed. (I1f2e8)
• We've added RendererParameters.isForScreenShot which will be true if the render is for a screen shot. Some watch faces with animations need to know this in order to make adjustments to ensure the best results. (I96d99)
• We've added WatchFaceExceptionReason to WatchFaceException to give some context to what went wrong. (I01d15)
• ComplicationDataSourceService.onImmediateComplicationRequest has been removed, instead ComplicationRequest.immediateResponseRequired has been added to signal that the provider needs to respond quickly (ideally responding in < 100ms). Note this functionality is guarded behind the privileged com.google.android.wearable.permission.USE_IMMEDIATE_COMPLICATION_UPDATE permission. (Ie6b23)
• Updated nullability in core and appcompat to match Tiramisu DP2 (I0cbb7)

Bug Fixes

• Now watchface app crashes with an exception if the schema validation fails (Ia400f)

Version 1.1.0-alpha03

February 9, 2022

androidx.wear.watchface:watchface-*:1.1.0-alpha03 is released. Version 1.1.0-alpha03 contains these commits.

API Changes

• We've added experimental support for hierarchical style schemas. We've added a new property to androidx.wear.watchface.style.UserStyleSetting.Option, childSettings which is initially only used by ListOption. This allows a hierarchy of styles to be described for use by Editor UIs, the underlying UserStyle is unchanged and is still a Map<String, ByteArray>. (Iaf6f4)
• We've added WatchFace.OverlayStyle which allows the watch face to configure the rendering of the system status overlay. (I8520d)
• We've introduced clearWithBackgroundTintBeforeRenderingHighlightLayer a new optional constructor parameter for CanvasRenderer (default is false), if set to true then the canvas will be cleared with the background tint color. (Ie01e5)
• Added androidx.watchface.complications.datasource.DEFAULT_CONFIGURATION_SUPPORTED metadata key which allows complication data sources to indicate they can provide a default value without any configuration (Icc0d4)
• It's common when editing a watch face for there to be both an interactive and a headless instance. To help save memory we've introduced Renderer.SharedAssets which allows a watch face renderer to share immutable data (e.g. textures and shaders) between instances. GlesRenderer.setEglConfig and GlesRenderer.setEglDisplay are deprecated, it was never intended for these to be settable, and doing so would have led to undefined behavior. (I0d9e7)
• We've added setNameResourceId & setScreenReaderNameResourceId (which reference string resources) to ComplicationSlot.Builder and corresponding getters in androidx.wear.watchface.client.ComplicationSlotState. This allows the system to fetch the names of ComplicationSlots for use in editors and screen readers. (If6c6a)
• WatchfaceMetadataClient.getUserStyleSchema and getComplicationSlotMetadataMap now throw WatchFaceException instead of RemoteException. (I86f11)
• onSynchronousComplicationRequest and related functions in ComplicationDataSourceService have been renamed to onImmediateComplicationRequest etc... (I87ba0)
• Watch face editors have much less screen real estate than companion editors, therefore it makes sense to support different icons for on watch face editors. This patch adds OnWatchEditorData (currently containing just an icon) to all UserStyleSettings and where appropriate their Option classes. (If1886)
• We've added @JvmOverloads to ListenableGlesRenderer's constructor for better java interop. (I2974a)

Bug Fixes

• ListenableGlesRenderer's constructor is now correctly marked as @Throws(GlesException::class), and it is now possible to extend this class in java. (Iac6d0)
• Fixes bug with PhotoImageComplicationData tapAction not being correctly handled (I1cc30)

Version 1.1.0-alpha02

January 12, 2022

androidx.wear.watchface:watchface-*:1.1.0-alpha02 is released. Version 1.1.0-alpha02 contains these commits.

New Features

• To aid debugging and testing, ComplicationData and related subclasses now have overridden hashcode, equals and toString methods making them easier to work with.

API Changes

• WatchfaceMetadataClient methods once again throw RemoteExceptions where appropriate, making it easier for client code to catch errors from the watch face. (I78785)
• ComplicationData and sub classes now have hashcode, equals and toString. (I24bc6)

Version 1.1.0-alpha01

December 15, 2021

androidx.wear.watchface:watchface-*:1.1.0-alpha01 is released. Version 1.1.0-alpha01 contains these commits.

New Features

• The UserStyleSchema and ComplicationSlots can now be defined in XML. This simplifies watch face construction. In addition, WatchFaceMetadataClient queries are faster because it doesn't need to bind to the service to get the metadata. The WatchFaceMetadataClient and ListenableWatchFaceMetadataClient are no longer experimental and will become part of the stable api. The system will be able to optionally support multiple instances of a watch face, each with distinct user defined styling options. These will be visible in the watch face picker. To opt into this a watch face must include the following meta data tag in its manifest.

      <meta-data
          android:name="androidx.wear.watchface.MULTIPLE_INSTANCES_ALLOWED"
          android:value="true" />
  

• Some watch faces have state that’s not captured in the UserStyle, to support this and multiple instances, the watch face's instance ID is now available via WatchState.watchFaceInstanceId.

• ComplicationData is now being cached to allow complications to be displayed immediately upon loading. Sometimes ComplicationData is cached in memory by the system and sometimes it is serialized by the watch face libraries. When serialized any associated tapAction will be lost, if this happens ComplicationData.tapActionLostDueToSerialization will return true and the watch face should render the complication differently (e.g. grayed out or semi-transparent) to signal that it can’t be tapped. The system will send updated ComplicationData with a tapAction as soon as possible.

• Some ComplicationData shouldn’t be cached for a long time, to support this we’ve added a more general feature ComplicationDataTimeline. This can be used to provide a sequence of time-gated ComplicationData to be delivered to the watch face which can be cached and updated automatically. For example, today's weather forecast at various times or multiple upcoming calendar events. ComplicationRequestListener has been extended with a new method onComplicationDataTimeline which you can use to return this data.

• DefaultComplicationDataSourcePolicy has been extended so you can specify the ComplicationType for the primary and secondary data sources.

• We've added support for synchronous complication providers where the complication is updated at a higher frequency than normal, up to once per second when the watch face is visible and non-ambient. Note: synchronous complication providers may have limited usage due to memory pressure concerns.

• The PendingIntentTapListener changes are likely to be reverted because we solved the underlying problem (it’s not possible for the watch face to launch activities for 5 seconds after pressing the home button) in the framework instead.

API Changes

• ComplicationData.isCached has been changed to tapActionLostDueToSerialization which is more useful when determining if the complication slot should be rendered differently to signal that it can't be tapped. (I6de2f)
• Added ComplicationDataTimeline to wear-complication-data-source. This can be used to provide a sequence of time-gated ComplicationData to be delivered to the watch face which can be cached and updated automatically. For example, today's weather forecast at various times or multiple upcoming calendar events. ComplicationRequestListener has been extended with a new method onComplicationDataTimeline which you can use to return this data. There's a new kotlin wrapper SuspendingTimelineComplicationDataSourceService for suspending data source services. (Idecdc)
• Added PendingIntentTapListener and WatchFaceControlClient.getPendingIntentForTouchEvent. This can help watch faces that need to launch intents in response to taps to work around a problem where the framework blocks launching new activities for 5 seconds after pressing the home button. (I98074)
• Introduced a per-watchface ComplicationData cache. The purpose of this is to allow the watch face to display last known complication data values upon loading until the system has had a chance to update them. There is a new API method WatchFaceControlClient.hasComplicationCache intended for OEMs. This may influence the system's strategy for sending complications to a watch face. In addition, ComplicationData has an isCached property and it is recommended that cached complications are rendered differently because the tapAction can not be cached and will be null in a cached complication. (I404b0)
• The watch face's instance ID is now available via WatchState.watchFaceInstanceId. Most watch faces won't need to use this, but if there's a per-watch face state that's not stored in the Schema then this is the key to use to identify the watch face instance. To help support this you can now provide an ID when calling WatchFaceControlClient.createHeadlessWatchFaceClient. (I1ff98)
• Extended DefaultComplicationDataSourcePolicy with the ability to set the default ComplicationTypes for the primary, secondary provider and for the fallback system provider. ComplicationSlot.defaultDataSourceType is now deprecated. (If0ce3)
• ComplicationSlot.configExtras is now mutable and can be updated before calling EditorSession.openComplicationDataSourceChooser(). (I6f852)
• Added WatchFace.setComplicationDeniedDialogIntent and setComplicationRationaleDialogIntent. These intents are launched to to show a rationale dialog before requesting complication permissions, and another dialog explaining that complication permission is needed when trying to edit a complication when permissions have been denied (the provider chooser will fail to open so the dialog is needed). (I3a29c)
• The UserStyleSchema and ComplicationSlots can now be defined in XML. This simplifies watch face construction and makes WatchFaceMetadataClient queries faster as they do not need to bind to the service to get the metadata. (I85bfa)
• Added InteractiveWatchFaceClient.supportsPendingIntentForTouchEvent so a client can determine if a watch face supports getPendingIntentForTouchEvent. (I0b917)
• WatchFaceMetadataClient and ListenableWatchFaceMetadataClient are no longer experimental. They can be used to efficiently obtain watch face metadata, where possible without opening a binder to the watch face. (Ibb827)
• Added support for synchronous complication providers where the complication is updated at a higher frequency than normal, up to once per second when the watch face is visible and non-ambient. To use this the provider must include a new androidx.wear.watchface.complications.data.source.SYNCHRONOUS_UPDATE_PERIOD_SECONDS metadata tag in its manifest and override onSynchronousComplicationRequest. Depending on the nature of the data source, it may also need to override onStartSynchronousComplicationRequests and onStopInteractiveComplicationRequests to get notifications of when the complication enters and exits interactive mode. (I8fe9d)

Version 1.0

Version 1.0.1

February 9, 2022

androidx.wear.watchface:watchface-*:1.0.1 is released. Version 1.0.1 contains these commits.

Bug Fixes

• Fixes bug with PhotoImageComplicationData tapAction not being correctly handled (I1cc30)

Version 1.0.0

December 1, 2021

androidx.wear.watchface:watchface-*:1.0.0 is released. Version 1.0.0 contains these commits.

Major Features of 1.0.0

The androidx.wear.watchface package is the new recommended library for developing WearOS watch faces. It has a number of new features over the old Wearable Support Library.

• User styling (e.g. to change the color palette, the style of the watch hands, the look of the hour marks etc) is directly supported by the library (see androidx.wear.watchface.style). It’s now much easier to develop an on watch face editor using androidx.wear.watchface.editor and your watch face can be edited from the system companion app without you needing to write any extra code.
• Best practices baked in. The library automatically generated screen reader content labels for complications (you can also add your own ones), and the framerate automatically drops when the battery is low and not charging to improve battery life.
• Less code is needed to develop a watch face, especially for complications where a lot of the boilerplate has moved into the library.

Bug Fixes

• Fix EditorSession.userStyle.compareAndSet (I6f676)
• Fix very short watch face delays (Iffb97)
• Dispatch InteractiveWatchFaceImpl.onDestroy on the UI thread (I83340)
• Fix several problems with broadcast receivers (I7d25f)

Version 1.0.0-rc01

November 3, 2021

androidx.wear.watchface:watchface-*:1.0.0-rc01 is released. Version 1.0.0-rc01 contains these commits.

Bug Fixes

• Fix dump() (called by adb shell dumpsys) which got broken by flow migrations. (087cf9e)

• Ensure proper ordering of writeDirectBootPrefs. We want writeDirectBootPrefs to always run after initStyleAndComplications or we risk delaying UI thread init.(37650ac)

• Ensure Renderer.onDestroy is called. In the scenario where the renderer has been created but WF init has not completed and Engine.onDestroy is called, we need to call Renderer.onDestroy. (f9952dc)

• Optimization/fix to isBatteryLowAndNotCharging. This patch moves the initial setup of isBatteryLowAndNotCharging earlier which means it can be done in parallel with createWatchFace. In addition we now listen to ACTION_POWER_DISCONNECTED. (ddffd80

• InteractiveWatchFaceClientImpl.isConnectionAlive to be false after close (ab9774e)

Version 1.0.0-beta01

October 27, 2021

androidx.wear.watchface:watchface-*:1.0.0-beta01 is released. Version 1.0.0-beta01 contains these commits.

Version 1.0.0-alpha24

October 13, 2021

androidx.wear.watchface:watchface-*:1.0.0-alpha24 is released. Version 1.0.0-alpha24 contains these commits.

API Changes

• Classes in package androidx.wear.watchface.complications have been moved into a new wear:watchface:watchface-complications project. Note this means you can't include this library as well as any previous alpha version of wear:watchface:watchface-complications-data because you'll get errors about duplicate classes. (I97195)
• Renderer.dump has been renamed to Renderer.onDump and has been annotated with @UiThread. (I44845)
• InteractiveWatchFaceClient.addWatchFaceReadyListener has been renamed to addOnWatchFaceReadyListener and removeWatchFaceReadyListener has been renamed to removeOnWatchFaceReadyListener. (I48fea)
• EditorSession getComplicationsPreviewData and getComplicationsDataSourceInfo are no longer suspend functions, instead they are StateFlow<> properties whose value is initially null. In ListenableEditorSession getListenableComplicationPreviewData and getListenableComplicationsProviderInfo have been removed in favor of the new StateFlow<> objects from the base class. If you need to listen to changes in java code, consider using androidx.lifecycle.FlowLiveDataConversions.asLiveData to convert to LiveData<>. (Ic5483)

Version 1.0.0-alpha23

September 29, 2021

androidx.wear.watchface:watchface-*:1.0.0-alpha23 is released. Version 1.0.0-alpha23 contains these commits.

New Features

The watchface library is now a single library group, and as a result the libraries have moved and you will need to update your gradle imports as follows:

API Changes

• Migrate the separate androidx.wear Watchface and complications libraries into androidx.wear.watchface library group. (b25f3c0)
• Added EditorRequest.canWatchFaceSupportHeadlessEditing to let a client know if a watchface editor supports headless editing. Note there will be some false negatives with this because support was added in asop/1756809 however it will return the correct value for all future watchfaces. (ca55590)
• Renderer now has a dump() method which can be overridden to add custom data to the information generated by ABD shell dumpsys activity service WatchFaceService. (95235f9)
• InteractiveWatchFaceClient.addWatchFaceReadyListener now specifies the executor first. (563ac2f)
• StateFlowCompatHelper has been removed. asLiveData (androidx.lifecycle.asLiveData) should be used instead. (bd35d3)
• CurrentUserStyleRepository.userStyle is no longer mutable. (I44889)
• WatchFaceReadyListener has been renamed to OnWatchFaceReadyListener. (Ic12a9)

Bug Fixes

• InteractiveInstanceManager.deleteInstance to call onDestroy This is needed to ensure InteractiveWatchFaceImpl gets garbage collected.(fce4af8, b/199485839)