wear protolayout

  
This library allows defining a set of UI layouts and non-UI expressions to be rendered/evaluated on a remote surfaces.
Latest Update Stable Release Release Candidate Beta Release Alpha Release
November 29, 2023 1.0.0 - - 1.1.0-alpha03

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.1.0-alpha03"

    // Use to implement support for Wear ProtoLayout
    implementation "androidx.wear.protolayout:protolayout:1.1.0-alpha03"

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

Kotlin

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

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

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

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

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.