wear protolayout

  
This library allows defining a set of UI layouts and non-UI expressions to be rendered/evaluated on remote surfaces.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
May 7, 2025 1.2.1 - 1.3.0-beta02 -

Declaring dependencies

To add a dependency on wear-protolayout, 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:

Groovy

dependencies {
    // Use to implement support for Wear ProtoLayout Expressions
    implementation "androidx.wear.protolayout:protolayout-expression:1.2.1"

    // Use to implement support for Wear ProtoLayout
    implementation "androidx.wear.protolayout:protolayout:1.2.1"

    // Use to utilize components and layouts with Material design in your ProtoLayout
    implementation "androidx.wear.protolayout:protolayout-material:1.2.1"
}

Kotlin

dependencies {
    // Use to implement support for Wear ProtoLayout Expressions
    implementation("androidx.wear.protolayout:protolayout-expression:1.2.1")

    // Use to implement support for Wear ProtoLayout
    implementation("androidx.wear.protolayout:protolayout:1.2.1")

    // Use to utilize components and layouts with Material design in your ProtoLayout
    implementation("androidx.wear.protolayout:protolayout-material: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-beta02

May 7, 2025

androidx.wear.protolayout:protolayout-*:1.3.0-beta02 is released. Version 1.3.0-beta02 contains these commits.

Bug Fixes

  • We have made an important improvement in the Typography design values that are applied on API 36 and above. This is because from API 36, all Tiles will be in the system font, so this change introduces better consistency in the Tiles carousel. (If316f)
  • Text,Spacer, ArcLine and DashedArcLine builders won’t throw if layoutConstraintsfor dynamic values are not set. Note that older renderers still require the layoutConstraints to be set and will ignore any dynamic value that doesn’t have it set. (Ic52e8)
  • Add heading semantics modifier to indicate that a layout element is heading for a section of content for accessibility purpose, and mark the text in the title slot of primaryLayout to be accessibility heading by default. (Iae1fb)
  • Final UX polish of the primaryLayout where space between title slot and main slot is decreased to 4dp instead of 6dp on smaller screens. (I0e056)
  • Apply default content description to textEdgeButton. (Ifaf8b)
  • Minor update to the avatarButton inner padding. (I0910b)

Version 1.3.0-beta01

April 9, 2025

androidx.wear.protolayout:protolayout-*:1.3.0-beta01 is released. Version 1.3.0-beta01 contains these commits.

New Features

The 1.3.0-beta01 release of Wear ProtoLayout indicates that this release of the library is feature complete and the API is locked (except where marked as experimental). Wear ProtoLayout 1.3 includes the following new functionalities and APIs:

  • Material 3 design comes to the watch, with components and layouts that are optimized for the round display and scale appropriately from small to large screen sizes
    • This includes Kotlin-only, protolayout-material3 library with more Compose-like APIs for the following components and features:
    • Dynamic color theme coming from the system and watch face with the latest Material3 theme for colors, shapes and typography
    • MaterialScope for taking care of all opinionated defaults and easier customization
    • iconEdgeButton, textEdgeButton
    • iconButton, textButton, button, imageButton, avatarButton, compactButton
    • titleCard, appCard, graphicDataCard, iconDataCard, textDataCard
    • circularProgressIndicator, segmentedCircularProgressIndicator
    • primaryLayout, buttonGroup
    • All components work across any SDK levels and ProtoLayout Renderer version, supplying sensible fallbacks where applicable
  • More Kotlin-friendly, Compose-like APIs for base ProtoLayout elements
    • LayoutModifier with ability to add the most of modifiers as chained functions (padding, contentDescription (including clearSemantics), background, clip, opacity etc.), convertible to the existing Modifiers object
    • LayoutColors and LayoutString as types with easier support for using dynamic fields and constraints
    • text and fontStyle
    • better map support for StateBuilder, including DynamicDataMap and factory methods such as intAppDataKey for easier creation of AppDataKey objects
  • Lottie animations support including option to set different triggers on when animation should start, for example when layout is loaded or when layout becomes visible
    • Improved gradient support:
    • Linear gradient API as part of Brush that can be used in Background modifiers for elements such as Box, Spacer, etc. …
    • Allow dynamic color values in ColorStop used for linear and sweep gradient
    • Existing Sweep Gradient in arc objects now supports dynamic colors and start and end angles
  • Platform data binding in protolayout-expression to receive information anytime that layout’s visibility is changed, which for example can be use to hide certain parts of the layout while tile is being swiped to
  • Testing library - protolayout-testing - has been added to support easier Unit test coverage for any ProtoLayout elements
  • New element DashedArcLine with improved set of features so that line can have dashes, as opposed to the existing ArcLine
  • ArcSpacer support for setting its length in DP dimension instead of degrees
  • Added roundness FontSetting axis applicable to some fonts

Version 1.3.0-alpha10

March 12, 2025

androidx.wear.protolayout:protolayout-*:1.3.0-alpha10 is released. Version 1.3.0-alpha10 contains these commits.

New Features

  • Add helper for Brush in kotlin Background Modifier. (I995de)
  • Mandatory Android Context field has been made public in MaterialScope to allow for easier usage in developers' functions that are creating components for Material3 tiles. (I7df73)

API Changes

  • Rename api platformVisibilityStatus to PlatformEventSources.isLayoutVisible and add a new experimental API PlatformEventSources.isLayoutUpdatePending. (Ie1e04)

Bug Fixes

  • Margins for primaryLayout are now properly rounded up instead, which can have effect on some layout up to 2dp space less for the main slot. (I8f5d3)
  • Clarification of default dynamic color theme in ProtoLayout Material3 components. (Iff5f3)
  • Typography.NUMERAL_* typographies are no longer tabular/monospace by default. If text is animating, it is highly recommended to add FontSetting.tabularNum() setting to it. In all other cases this monospace option is not needed and there will be more available characters by not using it. (Id3cd9)
  • Clarification of default dynamic color theme in ProtoLayout Material3 components. (I9d831)

Version 1.3.0-alpha09

February 26, 2025

androidx.wear.protolayout:protolayout-*:1.3.0-alpha09 is released. Version 1.3.0-alpha09 contains these commits.

New Features

  • Added experimental modifiers for enterTransition and exitTransition (I4a4d6)
  • We have added additional platform binding to receive the visibility status of full layout, whenever it's changed. (I250c3)
  • Allow injecting testing app state and platform data into LayoutElementAssertionsProvider for evaluating dynamic values. (Ib5fcb)
  • Add corner filters to the protolayout testing library (Ie2361)
  • ButtonColors, CardColors and ProgressIndicatorColors now support copy method, with optional override of some parameters. (Ie2054)

API Changes

  • Add dynamic data binding support to the testing library (Ib98de)
  • Fix imageButton when used with backgroundImage function by removing overlay. Additionally, allow for backgroundImage function to allow specifying null for overlay color, meaning that overlay won't be applied. (Ibec3c)

Bug Fixes

  • Changed default hasValueOfType method to throw UnsupportedOperationException instead of IllegalArgumentException. (Ia36c3)
  • Default color token values are update to reflect the latest spec. (I75d44)
  • Fixes for aliasing issue visible on arc lines in AndroidX tiles renderer. (I88190)

Version 1.3.0-alpha08

February 12, 2025

androidx.wear.protolayout:protolayout-*:1.3.0-alpha08 is released. Version 1.3.0-alpha08 contains these commits.

New Features

  • Add FontSetting list parameter for Material3 text. (Ic102d)
  • Added DynamicDataMap class which StateBuilder now supports for a better type safe Kotlin API for app states (I012ba)
  • Added factory methods such as intAppDataKey for easier creation of AppDataKey objects (Icea2a)
  • DynamicDataValue now has a hasValueOfType(Class<?>) method in addition to hasInt/hasColor/.... methods (I4f7a6)
  • We have added errorDim to the Material3 ProtoLayout ColorScheme, for high priority errors or emergency actions such as safety alerts. (Ia17bb)
  • We have added a guard against a crash when accessing the global reducemotion setting, which was triggered on some platforms where that setting was not provided. (I01e2c)

API Changes

  • addKeyToValueMapping is renamed to addToStateMap and DynamicDataMap.put methods are removed as they were redundant. (Ibe9dd)
  • Material3 Typography now supports roundness variable axis for system fonts that support this axis. ProtoLayout FontSetting supports roundness axis for fonts that support this axis. (I33eb5)
  • Renamed multilineAlignment to alignment in Material3 text method. (I2b66b)
  • Update the circular progress indicator to be Box type, also specify the mainContent in constructGraphic to be Box type (I5a3dc)
  • Better support for using circular progress indicator in graph (I039db)

Bug Fixes

  • Allow dynamic values in ColorStop and also for start/end angles in SweepGradient. (I0146d)
  • Docs fixes. (I4a63a)
  • Updated Material 3 components (graphicCard and avatarButton) to provide fallback when weight expand dimension is not supported (e.g. below API 33). Updated text component to fallback to TEXT_OVERFLOW_ELLIPSIZE_END when TEXT_OVERFLOW_ELLIPSIZE is not supported by the renderer. (I19e2c)
  • Docs update for PrimaryLayoutMargins. (Ibaf7b)

Version 1.3.0-alpha07

January 29, 2025

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

New Features

  • Added API option to set different triggers for Lottie animations. Additionally, added API for triggers fired when layout is visible (I8272d)
  • Added border, visibility and opacity modifiers. (I6d3dd)
  • Added avatar button to ProtoLayout Material3 component. (Idb5ae)
  • We are now allowing margins (side and in some cases bottom) to be customized in Material3 primaryLayout. (Ib22f6)
  • Add the segmented variant of the circular progress indicator. (I6a648)
  • Added compact button component to ProtoLayout Material3. (Ia3c5c)
  • Added pill shape button and image button components to ProtoLayout Material3. (Ifb88a)

API Changes

  • LayoutModfier.foldIn is now called foldRight to better reflect its expected behaviour (Idf242)
  • VisibleOnce trigger is now experimental. (Ib2d26)
  • Remove withOpacity from the public API as there is a graphics library alternative. (I030c2)
  • Renamed top level methods in LayoutString.kt and LayoutColor.kt to have Java friendly names. (I7aff0)
  • Removed non-ProtoLayout typographies in Material3. (Idd9ae)
  • Add suffix Color to fields in *Colors classes in Material3. (I2d114)

Bug Fixes

  • Add EdgeButton fallback implementation for older renderer without asymmetrical corners support. (I63364)
  • Add fallback implementation of the circular progress indicator with older renderer. (I0f134)

Version 1.3.0-alpha06

January 15, 2025

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

New Features

  • LayoutColor to support both static and dynamic color types (I4c89b)
  • Added ProtoLayout Material3 textButton component. (Id680d)
  • Add iconButton ProtoLayout Material3 component. (Ica3f0)
  • Added ProtoLayout Material3 button container component. (I17a38)
  • Added support for Chainable semantic modifiers to protolayout-material3 (I4af62)
  • Added ProtoLayout Material3 single segment CircularProgressIndicator (I2c8a2)
  • Added padding,metadata modifiers (I8720a)
  • Added background,clip and clickable modifiers (I35478)
  • Add LinearGradient to Brush and allow it to be used in the Background Modifier. (Ic4dea)
  • Add small size for appCard and titleCard. (I91f98)
  • Added ProtoLayout Material3 graphicDataCard component. (I92be7)
  • Added ProtoLayout Material3 iconDataCard and textDataCard components. (I4e1e4)
  • Added ProtoLayout Material3 appCard component. (Id4c57)
  • Abstract EdgeButtonColors to ButtonColors. (I83624)
  • Added ProtoLayout Material3 titleCard component. (I2dc72)

API Changes

  • ProtoLayout Material3 API now accepts LayoutString to support both static and dynamic texts. (I9c24a)

Bug Fixes

  • Add renderer implementation for inflating DashedArcLine (I0c700)
  • Renderer change for allowing ArcSpacer to take dp length. (I1437b)

Version 1.3.0-alpha05

December 11, 2024

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

New Features

  • Added LayoutString to support bindable layout string fields. (Ida650)
  • Added ProtoLayout Material3 card container component. (Ic985a)

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). (Id1f9b, b/326456246)

Version 1.3.0-alpha04

November 13, 2024

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

New Features

  • Updated Material3 shape to be a class with fields that hold the actual Corner value, same as in Wear Compose. (Ied8cd)
  • Updated Material3 colors to include ColorScheme concept, same as in Wear Compose. (If645e)
  • Add multiple commonly used matcher to the testing library. (Ie5cec)

Version 1.3.0-alpha03

October 30, 2024

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

New Features

  • Add LayoutElementAssertionsProvider, LayoutElementAssertion and LayoutElementMatcher to the testing library (Id1110)

Version 1.3.0-alpha02

October 16, 2024

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

New Features

  • Initial version of Material 3 library. Includes text, edgeButton, buttonGroup and primaryLayout components.

Security Fixes

  • As of this change, androidx compiles against protobuf 4.28.2 in order to address CVE-2024-7254. Upgrade your dependency on version 1.3.0-alpha01 of androidx.wear.protolayout:protolayout-proto and androidx.wear.protolayout:protolayout-external-protobuf to 1.3.0-alpha02 to address the vulnerability risk.

External Contribution

Version 1.3.0-alpha01

October 2, 2024

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

Bug Fixes

  • Clarified that Roboto and Roboto Flex font family names availability is device dependent. (I193be)
  • Enabled Roboto Flex font family in AndroidX Tile renderer. (I08e94)

Version 1.2

Version 1.2.1

October 16, 2024

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

Security Fixes

  • As of this change, androidx compiles against protobuf 4.28.2 in order to address CVE-2024-7254. Upgrade your dependency on version 1.2.0 of androidx.wear.protolayout:protolayout-proto and androidx.wear.protolayout:protolayout-external-protobuf to 1.2.1 to address the vulnerability risk.

Version 1.2.0

August 7, 2024

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

Important changes since 1.1.0

  • FontStyle has been updated to have additional font support for the variable axes and better font selection API to support upcoming Flex fonts.
  • Additional Modifiers support:
    • Transformation modifier offering translation, rotation and scaling with or without animations.
    • Specifying different values (horizontal and vertical) for each corner radius.
  • Improved accessibility of all touch targets by extending the tappable area of any element that uses Clickable modifier to be at least 48dp by 48dp.
  • Improved PrimaryLayout and EdgeContentLayout by adding setResponsiveContentInsetEnabled to better support responsive behavior of these layouts across different screen sizes and improve Tiles consistency.
  • Improved scaling/non-scaling of the Material Text for Android 14's non-linear font scaling.
  • Improved support for RTL layout direction on all arc elements.

Additional changes

Version 1.2.0-rc01

July 24, 2024

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

Bug Fixes

  • We have fixed the standard Material Chip so it can be used as an icon only if none of the primary or secondary label is passed in. (Iceef9)
  • Documentation for Material layouts has been updated to include visuals from the relevant page for easier understanding of layouts. (I0256a)

Version 1.2.0-beta01

July 10, 2024

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

New Features

The 1.2.0-beta01 release of Wear ProtoLayout indicates that this release of the library is feature complete and the API is locked (except where marked as experimental). Wear ProtoLayout 1.2 includes the following new functionalities and APIs:

  • FontStyle has been updated to have additional font support as following:
    • Setting different font variation setting such as FontSetting.weight and FontSetting.width
    • Setting the same width for all numeric characters - tabular numerals (FontSetting.tnum font feature setting)
    • Improved font selection APIs to support the upcoming flex fonts by specifying preferred font family names to be used.
  • Extended Corner modifier to support specifying each CornerRadius with a separate horizontal and vertical values to allow building elements with asymmetric corners.
  • Added a new Transformation modifier offering translation, rotation and scaling of LayoutElement. These transformations can be animated by using dynamic values.
  • Added setArcDirection with Clockwise, CounterClockwise and Normal options to all arc elements (Arc, ArcLine and ArcText) for better support in different layout directions (such as LTR and RTL).
  • Improved accessibility of all touch targets by extending the tappable area of any element that uses Clickable modifier to be at least 48dp by 48dp.
  • Improved PrimaryLayout and EdgeContentLayout by adding setResponsiveContentInsetEnabled to better support responsive behavior of these layouts across different screen sizes and improve Tiles consistency. Added linter warning to suggest usage of these APIs with a quick fix.
  • Improved scaling/non-scaling of the Material Text for Android 14's non-linear font scaling.

API Changes

  • Default font family name (DEFAULT_SYSTEM_FONT) is removed as it is implied by not using the preferredFontFamilies API. (I39dab)
  • Parameter passed in to the FontSetting.width should be positive. (I1266f)

Version 1.2.0-alpha05

June 26, 2024

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

New Features

  • Add hasText method to Material.CompactChip to check whether the text content has been set. (I6e8fc)

API Changes

  • FontFamily const are moved to be in FontStyle instead of its Builder class. (I06ced)
  • Update FontSetting.weight and FontSetting.width API to include Range annotations and change weight's parameter to be int. (Ia726c)

Bug Fixes

  • Non-scalable texts in Material library now work correctly with Android 14's non-linear font scaling. (I6601e)

Version 1.2.0-alpha04

May 29, 2024

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

API Changes

  • Added asymmetrical corners API to be able to specify separately each corner’s radius with 2 values. (Icbd69)
  • Extended the FontSetting API to include:
    • font feature setting such as setting the font to be tabular. (If12b7)
    • font variation setting such as setting custom width for variable fonts. (I2b36d)
  • Added font family API to FontStyle to allow specifying an order list of which font families should be used. (Iba9f5)
  • Renamed constants for space height between content and secondary label in Material’s LayoutDefaults that were initially prefixed with “Edge content” to be more generic as they can be applied to both PrimaryLayout and EdgeContentLayout. (I4dc32)

Bug Fixes

  • Renamed naming for variable font axes from axisName to axisTag. (I02ba3)

Version 1.2.0-alpha03

May 14, 2024

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

New Features

  • Added API for setting custom weight values for FontStyle. (I7390a)

Bug Fixes

  • Fix the failure in getTouchDelegateInfo due to empty target map. (I2accf)

Version 1.2.0-alpha02

May 1, 2024

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

API Changes

  • We've added support for disabling ripple feedback on individual clickable elements. (If1ede)
  • The API for transformation has been removed from ArcModifiers as they don't support that feature (Ic0827)
  • ArcDirectionProp Builder now expects a value in the constructor. (I76ada)
  • The PlatformDataValues.Builder.putAll method will allow merging one PlatformDataValue into another one. (I50ba3)
  • Text#setIsScalable is renamed to Text#setScalable. (If920e)
  • Material Text can set whether to use scalable size (grows when user font size is changed) or not. (Ibc849)
  • We've added the option to set content description to TitleChip. (I5d21f)
  • Fixed CompactChip to work correctly with icon only and update the API to allow this option. (I6589e)

Bug Fixes

  • Fixed an issue of potential duplicate platform data during initialization. (Iba0fd)
  • Introduce a new getter to DynamicDataNode to retrieve node cost. The cost is used when acquiring dynamic node quota. Currently, Nodes with fixed values will have a cost of 0, all the other nodes will have a cost of 1. (Ia33e1)
  • Remove counting logic from the NO_OP_QUOTA_MANAGER. (Ib50b8)
  • We have added a lint rule to report a warning when PrimaryLayout is used without setResponsiveContentInsetEnabled and provide a quick fix. (I12025)
  • There is a limit to a number of dynamic expression nodes. (Iffae8)

Version 1.2.0-alpha01

March 6, 2024

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

New Features

  • ProtoLayout Arc elements now have the option to add ArcDirection (Clockwise, Counterclockwise or Normal) to it. Adding this behavior to Arc, ArcLine or ArcText will fix their behavior on RTL layouts. (I90699)
  • EdgeContentLayout has been updated with a new setResponsiveContentInsetEnabled setter to achieve better alignment with the UX guidelines, consistency in Tiles by having primary label at the fixed place on top and responsive inset for labels. (I60175)
  • We have added PrimaryLayout.setResponsiveContentInsetEnabled that adds responsive inset to the primary label, secondary label and bottom chip in this layout, to avoid that content going off the screen edge. (I0c457)
  • Adds method to remove outer margins from CircularProgressIndicator so it can be used as a smaller component. (I55c06)

API Changes

  • Tiles renderer now excludes font padding on all text elements by default, without an option to include it. (I3e300)

Bug Fixes

  • Fixed Text alignment issue when ellipsize, letter spacing and center align are all used on Text. (I716c7)
  • Add a workaround for a skia arc drawing issue. (I08f09)
  • Fix ArcLine drawing direction for RTL layouts. (I6c141)

Version 1.1

Version 1.1.0

February 7, 2024

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

Important changes since 1.0.0

  • Gradient support and better representation of lengths larger than 360 degrees in ArcLine.
  • Date-time formatting supports different time zones for dynamic data types.
  • Better text autosizing and ellipsizing options, to handle truncated text.
  • Spacer supports expanded dimensions with optional weight.
  • Schema version requirement annotation to all ProtoLayout APIs.
  • Extended target area to any Clickable element to 48 dp x 48 dp, to satisfy accessibility requirements.
  • Font padding is turned off by default and is the only behavior across all Text elements and Material components that contain text.

Additional changes

Version 1.1.0-rc01

January 24, 2024

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

Bug Fixes

  • PlatformTimeUpdateNotifierImpl ticks immediately after enabling update. (I77145)
  • CircularProgressIndicator has been fixed for RTL layouts. From now on, it will go clockwise in all cases. (I95ee3)
  • Add a workaround for a skia arc drawing issue. (I08f09)

Version 1.1.0-beta01

January 10, 2024

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

New Features

The 1.1.0-beta01 release of Wear ProtoLayout indicates that this release of the library is feature complete and the API is locked (except where marked as experimental). Wear ProtoLayout 1.1 includes the following new functionalities and APIs:

  • ArcLine now supports gradient by adding Brush with SweepGradient and having a shadow on the cap to better represent length larger than 360 degrees by adding Shadow on the existing StrokeCap.
  • DynamicInstant has support for zoned date-time formatting. DynamicInstant and DynamicDuration can be used as state or platform data types.
  • Autosizing feature for text size that allows setting multiple sizes to FontStyle.setSizes where the Text size will automatically scale based on the space it has inside of the parent. Additionally, we improved ellipsizing options for text that overflows by adding TEXT_OVERFLOW_ELLIPSIZE and deprecating TEXT_OVERFLOW_ELLIPSIZE_END.
  • Spacer now supports having expanded dimensions with optional weight. For building ExpandedDimensionProp we have added a helper method DimensionBuilders.weight.
  • Support for dynamically hiding and unhiding layout elements with Modifier.visible. This includes having dynamic values in BoolProp.
  • All ProtoLayout APIs now have schema version requirement annotation and version can be checked before calling a newer API.
  • Every element that has Clickable now has its target area extended to at least 48x48 in the renderer to better support accessibility requirements.
  • Following other Material components and Compose initiatives, we have now turned off font padding by default on all Text elements. Additionally, AndroidTextStyle and related setters have been removed from the public API. with following bug fixes:
  • Added a setter for positioning the edge content in EdgeContentLayout so it can be positioned before other content.
  • Consistently throwing an exception when encountering an unrecognized enum value.
  • Invalidate the result of an expression when it yields an invalid numeric value (NaN or infinite) or throws an ArithmeticException.

API Changes

  • Updates to SweepGradient API to allow accepting either colors or ColorStops in the constructor. (I6676f)

Bug Fixes

  • Adding a restricted API and renderer support for setting a direction in which arc elements are drawn. (Idef5a)
  • RoundMode defaults to Floor in FloatToInt32Node when unspecified. The node will still throw an exception if the provided RoundMode is unrecognized. (I1b2d8)

Version 1.1.0-alpha04

December 13, 2023

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

New Features

  • VersionInfo class not implements the Comparable interface. (I8d13c)
  • Renderer now supports TEXT_OVERFLOW_ELLIPSIZE option. (I7f085)

API Changes

  • Text overflow option TEXT_OVERFLOW_ELLIPSIZE_END is now deprecated. Please use the new API TEXT_OVERFLOW_ELLIPSIZE with very similar behavior. (I822d8)
  • Following other Material components and Compose initiatives, we have now turned off font padding by default on all Text elements. Additionally, AndroidTextStyle and related setters have been removed from the public API. (I79094, Ib0b03, I32959, Iaf7d5, Ifa298, I0a4ae, Ida9d3)
  • Modifier.hidden is replaced with Modifier.visible (I56902)
  • FontStyle#setSizes now accepts int instead of SpProp arguments. (I02b37)

Bug Fixes

  • Throw an exception when encountering an Undefined or Unrecognized enum value. (I9d2cf)
  • Refactor DynamicTypeBindingRequest. (I27b57)
  • Invalidate the result of an expression when it yields an invalid numeric value (NaN or infinite) or throws an ArithmeticException. (I681ae)

Version 1.1.0-alpha03

November 29, 2023

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

New Features

  • Add experimental support for dynamically hiding/unhiding layout elements (I64a78)
  • Add dynamic value support to BoolProp (I2fe96)
  • Add schema version requirement annotation to ProtoLayout APIs (I0f03c)
  • Extending the API with the new option in TextOverflow for ellipsizing the Text in a fixed parent container even when max lines is not reached (but there's not enough space for Text). (I110a9)
  • Added helper method DimensionBuilders.weight for building ExpandedDimensionProp with weight. (I4f72b)
  • DynamicInstant and DynamicDuration can be used as state or platform data types. (I6819f)

API Changes

  • Update The API to hide DynamicZonedDateTime and move all its operations to DyanamicInstant (I34b94)
  • Spacer now supports Expanded dimension for width/height. (Ie7c94)
  • Support click target area extension in Renderer (I39c79)

Version 1.1.0-alpha02

November 15, 2023

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

New Features

  • Added an ArcLine StrokeCap Shadow field to the API. (I830ec)
  • Extending the API to be able to specify Spacer's width or height to expand. (I757ca)
  • We have added an experimental API to automatically scale the text size based on the space it has inside of the parent. (Ibbe63)
  • Support minimum clickable size (I178e3)
  • Added renderer support for StrokeCap Shadow. (I48b17)
  • Add renderer support for Sweep Gradient in ArcLine. (I4d5bb)

Version 1.1.0-alpha01

October 18, 2023

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

New Features

  • Added a brush option to Arcline, with support for SweepGradient. (Ie7ce3)
  • Added support for zoned date-time formatting. (Ibfae0)
  • Added protos and java Wrappers required for zoned date-time formatting. (I97126)
  • Added getters for reading back the value stored in a DynamicDataValue. (Ie6cea)
  • Added a setter for positioning the edge content in EdgeContentLayout so it can be positioned before other content. (Ie8e8a)

Bug Fixes

  • Fixed an issue when an expression with multiple time data source registrations was not being updated immediately. (I8e1a8)
  • Fixed a bug to center root element during diff updates. (Ie48f7)
  • Unset (or empty) layout constraint values will not be ignored anymore. (Ibc785)
  • Reduced delay between a layout becoming visible and its pipeline nodes being initialized. (I38d4e)

Version 1.0

Version 1.0.0

August 9, 2023

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

Major features of 1.0.0

ProtoLayout library introduces APIs for creating layouts and expressions that can be used across different Wear OS surfaces. For example Tiles library uses these APIs to support platform data binding (for faster tile data updates) and animations.

Version 1.0.0-rc01

July 26, 2023

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

  • To migrate from Tiles to ProtoLayout, please follow the instructions here.

API Changes

  • We have removed setLayoutConstraintForDynamicAnchorAngleand getLayoutConstraintForDynamicAnchorAngle methods from Arc element. These methods have been added by mistake and they didn't have any effect on the provided layout. (If7d01)
  • We have limited the maximum depth that a ProtoLayout’s layout can have to 30 nested LayoutElements. (I8a74b)

Bug Fixes

  • We have added a check to throw if DynamicColor has been set for a SpanText. (I0e5bc)
  • It is clarified that DAILY_CALORIES data source unit is kcal. (Iaa785)

Version 1.0.0-beta01

June 21, 2023

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

New Features

  • Allow setting clock for time binding tests. (I05622)

API Changes

  • PlatformDataReceiver.onData() and StateBuilders.Builder.addKeyToValueMapping now accept type-safe mapping of DynamicDataKey to DynamicDataValue rather than unsafe generics. That means that DynamicDataValue is now typed with its DynamicType. HEART_RATE_ACCURACY_X constants moved to the root of PlatformHealthSources, to match other Android constants positioning. HEART_RATE_ACCURACY_X int constants are now used directly in DynamicHeartRateAccuracy.constant() and DynamicHeartRateAccuracy.dynamicDataValueOf() instead of value constant. (I82ff5)
  • The PlatformHealthSources.Constants class was instantiable by mistake. This has been fixed now. (Icb849)
  • PlatformTimeUpdateNotifier#setReceiver now receives Runnable instead of Supplier function and Executor to notify on. (I9d938)
  • We have changed the parameter type in the PlatformTimeUpdateNotifier#setReceiver from Callable to Supplier. (I664bf)
  • CompactChip and TitleChip now support adding an icon to it. (I5a01e)

Bug Fixes

  • Update Prop messages with dynamic fields to use oneof instead (I81739)
  • Reuse setters implementation for overloads that have setters (Ied70c)
  • Properly record fingerprints in setters that have overloads (I86ed2)

Version 1.0.0-alpha11

June 7, 2023

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

New Features

  • We've added a PlatformDataKey for heart rate accuracy. (I7f9b8)

API Changes

  • Rename StateBuilders#getIdToValueMapping to getKeyToValueMapping and change the return type to Map<<AppDataKey<?>,DynamicDataValue>. (Iaa7ae)
  • Make StateStore a final class (I408ca)
  • TimeGateway interface has been replaced by PlatformTimeUpdateNotifier in protolayout-expression-pipeline library which provides desired frequency for updating time data. (I60869)
  • Rename register/unregisterForData in PlatformDataProvider to set/clearReceiver (I14b02)
  • In Material Text, getExcludeFontPadding has been renamed to hasExcludeFontPadding. (Iea01d)
  • Setter for perfectly aligning label was added to all chip components. All chips now have min tappable target applied. (I8ae92)
  • LayoutDefaults#BUTTON_MAX_NUMBER has been renamed to MAX_BUTTONS. (I84788)
  • DAILY_DISTANCE is renamed to DAILY_DISTANCE_M. (I4f758)

Bug Fixes

  • Update Prop types docs to clarify why static value is enforced. Specify the default value used if static value wasn't provided. (I155aa)
  • PlatformDataKey namespaces should follow Java style naming. (I47bda)

Version 1.0.0-alpha10

May 24, 2023

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

New Features

  • Add AppDataKey for accessing app pushed state; Add PlatformDataKey for accessing platform data; Add namespace support in StateStore. (I7985e)
  • Support Equal and NotEqual operations for DynamicBool. (I6a0c1)

API Changes

  • FontStyles class is now final (Iaa2ea)
  • LayoutElementBuilders#FontStyles has been deprecated. Please use androidx.wear.protolayout.Typography or create your own FontStyle. (Ic929b)
  • Hide Action#Builder nested interface from Action interface. Implementations of Builder are already provided by LoadAction and LaunchAction classes. (I1d70c)
  • Allow using DynamicFloat with FloatProp. Note that FloatProp do no require layout constraints as it's not used as a layout changing prop. (I286ac)
  • The LoalAction and SetStateAction actions are removed as they were not really supported yet. (I5d6a6)
  • Added support for ARGB_8888 format for inline image resources. (I8a07c)
  • Rename StateEntryValue to DynamicDataValue, and update the state APIS to use the DynamicDataKey (If1c01)
  • We are limiting the number of entries that are allowed in the StateStore in order to ensure that memory usage and state update time are well contained and controlled for each instance of the StateStore. As a result, the developer needs to ensure that they do not have more than MAX_STATE_ENTRY_COUNT entries in the map otherwise they will get an IllegalStateException when creating or updating the StateStore. (Ibadb3)
  • Hide OnLoadTrigger and OnConditionMetTrigger classes, and rename setTrigger to setCondition for OnConditionMetTrigger. (Ibf629)
  • For performance and compatibility reasons, the ProtoLayout renderers won't support the full set of features in AnimatedVectorDrawable resources. We're marking those APIs as experimental until we can define the supported set. (Ic6daf)
  • Added dynamic types for daily distance, daily calories and daily floors. Keys for platform health sources are now under PlatformHealthSources.Keys (Ib7637)
  • The Easing.cubicBezier method replaces the CubicBezierEasing.Builder. With that the EasingFunction class is removed and the easing constants from that class are now directly accessible from the Easing interface. In addition setInfiniteRepeatable is replaced by INFINITE_REPEATABLE_WITH_RESTART and INFINITE_REPEATABLE_WITH_REVERSE (Ib41e7)
  • Implement PlatformDataProvider to provide heart rate and daily steps. SensorGateway interface is removed from public API. (I55b84)
  • Add PlatformDataProvider, and update StateStore to register to PlatformDataProvider when the provider's supported key is required by node from expression pipeline. (Ib616a)
  • SensorGateway is no longer Closeable as it no longer maintains any state. (I6b4f7)
  • Allow using FloatProp with DynamicFloat for progress in CircularProgressIndicator. This is supported for renderers supporting version 1.2. Old renderers will fallback to the staticValue if provided, otherwise to 0 (I0d91b)
  • MultiButtonLayout constants have been refactored into LayoutDefaults.MultiButtonLayoutDefaults class which now contains those for button sizes depending on a number of buttons in the layout. (I13973)
  • Support using StringProp with DynamicString in Material Text. This is supported for renderers supporting version 1.2. Old renderers will fallback to the provided static value. Update Text#getText return type from String to StringProp. (I7275b)

Version 1.0.0-alpha09

May 10, 2023

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

New Features

  • We've added an experimental extension layout element. Note that this can't be used by default and requires a renderer extension capable of understanding the layout element. (I6581d)
  • Added StrokeCap support for ArcLine. (I94951)
  • Added support for Conditional Instant operation. (I489a7)
  • Added support for Conditional Duration operation. (Iab469)
  • Added support for creating duration from seconds. (Ib5fa1)

API Changes

  • 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)
  • Add support for dynamic content description in protolayout-material. (I62c8e)
  • Use long and @IntRange for duration and delay in AnimationParameters. (I388b6)

Version 1.0.0-alpha08

April 19, 2023

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

New Features

  • AndroidTextStyle has been added to LayoutElementBuilders. (I8d967)
  • We have added support for setting excluding font padding in ProtoLayout Material Text. (I17f5d)
  • ARGB_8888 is now supported for inline images. (I18c1e)
  • DynamicColor now supports onConditionoperation. (I10927)

API Changes

  • Support custom duration for reverse animation (I3251f)
  • We've added the SemanticDescription modifier. In addition, ContentDescription is not bindable. (I3f1d)
  • The DynamicBool.isFalse()method is now replaced with DynamicBool.negate() and the DynamicBool.isTrue() is removed. In addition NaN DynamicFloat values and narrowing a DynamicInt32 to a DynamicFloat now emit an invalid dynamic result. (I6ac1e)
  • Int and float formatters now use the Builder pattern. (Ieb213)

Bug Fixes

  • Fallback static value has been removed from animatable fields. (Ifcb01)
  • DynamicTypeValueReceiver#onPreUpdate has been removed. (I2dc35)
  • Length of Strings in dynamic expressions are now capped. (I4c93)
  • The gradle dependencies are now correctly set to api instead of implementation when required. (I40503)

Version 1.0.0-alpha07

April 5, 2023

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

New Features

  • Add dynamic value support to StringProp (I04342)
  • Mark bindable layout elements (Ia110b)

API Changes

  • sensorGateway#registerSensorGatewayConsumer takes data type as a parameter instead of method in Consumer. (Icf314)
  • ObservableStateStore has been renamed 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)

Bug Fixes

  • Correctly propagate signals from platform sensor sources to downstream nodes (I5a922)

Version 1.0.0-alpha06

March 22, 2023

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

New Features

  • We've added an experimental API for using heart rate and daily steps in dynamic expressions (Ifd711)
  • We have added support for reverse and forward delay for animations. (Ic25f7)
  • We've added DynamicColor support to Border and Background
  • We've added dynamic value support to types in DimensionBuilder
  • Layout and components from tiles-material are moving to protolayout-material

API Changes

  • LoadActionListener has been added to ProtoLayoutViewInstance. (If7806)

Bug Fixes

  • Added FloatNodesTest (Id7281)
  • Fix renderer crash when unable to load structured bitmap.

Version 1.0.0-alpha05

March 8, 2023

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

New Features

  • We've added an experimental "content update" animation to the Modifiers object. This animation will trigger whenever the element (with this modifier) or one of its children changes during a layout update. (bd03e5d)

API Changes

  • We've added forwardRepeatDelayMillis and reverseRepeatDelayMillis to Repeatable. We've also renamed delayMillis in AnimationSpec to startDelayMillis (Ifb266)
  • DynamicTypeEvaluator.bind methods now accept an Executor. (I346ab)
  • We've added the startEvaluation method to the BoundDynamicType to trigger the evaluation after the dynamic type is bound. (I19908)

Bug Fixes

  • The Animator object will be reused for subsequent animations of a single element. (Ia3be9)

Version 1.0.0-alpha04

February 22, 2023

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

New Features

  • ObservableStateStore now informs the listeners when a key is removed too.
  • We've added renderer schema version and font scale to DeviceParameters (which can be used to conditionally create layouts in response to different versions and font settings).
  • We've added support for animating DynamicInt32 values (I05485)
  • We've added OnLoad and OnConditionalMet triggers. These can be used to start animations that support a trigger.
  • We've added layout weight for expanded dimensions and min size for wrapped dimensions.
  • We've added duration and instant dynamic types. These can be used to represent a time instant or duration in a dynamic expression.
  • We've added support for AnimatedVectorDrawable and SeekableAnimatedVectorDrawable as layout resources.

API Changes

  • Sensor data requires API 29+. (I8099e)
  • We've added two launchAction helper methods (for launching Activities).

Bug Fixes

  • Rename set/getSpec to set/getAnimationSpec in Tiles animation (I3d74b)

Version 1.0.0-alpha03

February 8, 2023

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

New Features

  • We have added toByteArray() and fromByteArray() to Dynamic types in protolayout-express library.
  • We have added toString() to Dynamic types in protolayout-expression library.
  • We have added evaluation support for Dynamic types. The DynamicTypeEvaluator class from the protolayout-expression-pipeline library can be used to evaluate (and receive updated values) for a previously create Dynamic type (DynamicString, DynamicFloat, …)
  • When animations can't be played (either because they are disabled by the evaluator, or the number of running animations has reached the set limit), the static values set on the animatable node will be used to replace the animation.

Version 1.0.0-alpha02

January 25, 2023

androidx.wear.protolayout:protolayout:1.0.0-alpha02, androidx.wear.protolayout:protolayout-expression:1.0.0-alpha02, and androidx.wear.protolayout:protolayout-proto:1.0.0-alpha02 are released. Version 1.0.0-alpha02 contains these commits.

New Features

  • Layout builders from androidx.wear.tiles:tiles are moving to androidx.wear.protolayout:protolayout. The ones in androidx.wear.tiles:tiles will be deprecated in one of the next alpha releases.

Version 1.0.0-alpha01

January 11, 2023

androidx.wear.protolayout:protolayout-expression:1.0.0-alpha01 and androidx.wear.protolayout:protolayout-proto:1.0.0-alpha01 are released. Version 1.0.0-alpha01 contains these commits.

New Features

  • This release introduces a new library "ProtoLayout Expression" for creating expressions from dynamic variables.