Skip to content

Commit 3d4a341

Browse files
hunterstichhunterstich
committed
[Motion] Updated documentation to include motion theming
PiperOrigin-RevId: 357937188
1 parent edd2eb5 commit 3d4a341

File tree

1 file changed

+146
-1
lines changed

1 file changed

+146
-1
lines changed

‎docs/theming/Motion.md‎

Lines changed: 146 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ information, go to the
2020
[Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md)
2121
page.
2222

23+
_**Note:** [Motion theming](#theming) will only be available in Material
24+
Components for Android version `1.4.0-alpha01` and above._
25+
2326
Material Components for Android provides support for all four motion patterns
2427
defined in the Material spec.
2528

@@ -188,6 +191,14 @@ override fun onCreate(savedInstanceState: Bundle?) {
188191
}
189192
```
190193

194+
_**Note:** When setting a `Hold` or `MaterialElevationScale` transition, it’s
195+
important that the transition matches the duration of the
196+
`MaterialContainerTransform` it’s paired with. If explicitly setting a duration
197+
on `MaterialContainerTransform` with `setDuration`, use the same value.
198+
Otherwise, prefer the `MaterialContainerTransform(Context, boolean)` constructor
199+
which loads theme-based values upfront so `Hold` or `MaterialElevationScale`’s
200+
duration can be accurately set using `MaterialContainerTransform.getDuration`._
201+
191202
Alternatively, to subtly scale and fade Fragment A while the container transform
192203
is playing, set FragmentA's exit and reenter transitions to a
193204
`MaterialElevationScale` transition. This will help to reinforce the spatial
@@ -360,6 +371,29 @@ customize the look and feel of the animation:
360371
Element | Attribute | Related method(s) | Default value
361372
-------------- | ------------------------ | --------------------------------- | -------------
362373
**Shape** | `transitionShapeAppearance` | `getStartShapeAppearanceModel`<br/>`setStartShapeAppearanceModel`<br/>`getEndShapeAppearanceModel`<br/>`setEndShapeAppearanceModel` | `null`
374+
**Duration (incoming)** | `motionDurationLong1` | `getDuration`<br/>`setDuration` | `300ms`
375+
**Duration (outgoing)** | `motionDurationMedium2` | `getDuration`<br/>`setDuration` | `250ms`
376+
**Easing** | `motionEasingStandard` | `getInterpolator`<br/>`setInterpolator` | `cubic-bezier(0.4, 0.0, 0.2, 1)`<br/>`FastOutSlowIn`
377+
**Motion path** | `motionPath` | `getPathMotion`<br/>`setPathMotion` | `linear`
378+
379+
_**Note:** By default, `MaterialContainerTransform` uses different durations
380+
when incoming vs. outgoing. Calling `setDuration` on an instance of
381+
`MaterialContainerTransform` will override this behavior, causing the passed
382+
duration to be used both when incoming and outgoing. If you would like different
383+
durations for incoming and outgoing animations, you should create and set
384+
separate instances of `MaterialContainerTransform` for entering and returning
385+
transitions with the desired values. Alternatively, update the duration theme
386+
attributes._
387+
388+
`MaterialContainerTransform` provides two constructors - an empty parameter
389+
constructor and a `(Context, boolean)` constructor. The `(Context, boolean)`
390+
constructor is used to load theme-values upfront, making it possible to query
391+
for duration, interpolation and motion path if other transitions or animations,
392+
such as `Hold` and `MaterialElevationScale`, depend on these values from
393+
`MaterialContainerTransform`.
394+
395+
See the [Motion Theming section](#theming) for details on how to systematically
396+
update motion.
363397

364398
#### Container transform properties
365399

@@ -694,6 +728,15 @@ override fun onCreate(savedInstanceState: Bundle?) {
694728
}
695729
```
696730

731+
#### Shared axis attributes
732+
733+
Element | Attribute | Related method(s) | Default value
734+
-------------- | ------------------------ | --------------------------------- | -------------
735+
**Duration** | `motionDurationLong1` | `getDuration`<br/>`setDuration` | `300ms`
736+
**Easing** | `motionEasingStandard` | `getInterpolator`<br/>`setInterpolator` | `cubic-bezier(0.4, 0.0, 0.2, 1)`<br/>`FastOutSlowIn`
737+
738+
See the [Motion Theming section](#theming) for details on how to systematically
739+
update motion.
697740

698741
## Fade Through
699742

@@ -936,6 +979,16 @@ override fun onCreate(savedInstanceState: Bundle?) {
936979
}
937980
```
938981

982+
#### Fade through attributes
983+
984+
Element | Attribute | Related method(s) | Default value
985+
-------------- | ------------------------ | --------------------------------- | -------------
986+
**Duration** | `motionDurationLong1` | `getDuration`<br/>`setDuration` | `300ms`
987+
**Easing** | `motionEasingStandard` | `getInterpolator`<br/>`setInterpolator` | `cubic-bezier(0.4, 0.0, 0.2, 1)`<br/>`FastOutSlowIn`
988+
989+
See the [Motion Theming section](#theming) for details on how to systematically
990+
update motion.
991+
939992
## Fade
940993

941994
The **fade** pattern is used for UI elements that enter or exit within the
@@ -1009,5 +1062,97 @@ Element | Primary transition | Secondary transition
10091062
---------------- | ------------------ | --------------------
10101063
**MaterialFade** | `Fade` | `Scale`
10111064

1012-
10131065
<!-- Todo: Add snippet of variant -->
1066+
1067+
#### Fade through attributes
1068+
1069+
Element | Attribute | Related method(s) | Default value
1070+
-------------- | ------------------------ | --------------------------------- | -------------
1071+
**Duration (incoming)** | `motionDurationShort2` | `getDuration`<br/>`setDuration` | `150ms`
1072+
**Duration (outgoing)** | `motionDurationShort1` | `getDuration`<br/>`setDuration` | `75ms`
1073+
**Easing** | `motionEasingLinear` | `getInterpolator`<br/>`setInterpolator` | `cubic-bezier(0 0, 1, 1)`<br/>`Linear`
1074+
1075+
See the [Motion Theming section](#theming) for details on how to systematically
1076+
update motion.
1077+
1078+
## Theming
1079+
1080+
Motion theming will only be available in Material Components for Android version
1081+
`1.4.0-alpha01` and above.
1082+
1083+
The Material motion system is backed by a limited number of slots which
1084+
transitions use by default to create a consistent, branded feel. These slots are
1085+
implemented as theme attributes, similar to color or shape attributes.
1086+
1087+
### Easing
1088+
1089+
Easing theme attributes define a set of curves that can be inflated and used as [Interpolators](https://developer.android.com/reference/androidx/core/animation/Interpolator).
1090+
1091+
Attribute | Default value | Description
1092+
-------------- | ------------------------ | ---------------------------------
1093+
**?attr/motionEasingStandard** | `cubic-bezier(0.4, 0.0, 0.2, 1)`<br/>`FastOutSlowIn` | Easing used for elements that begin and end at rest.
1094+
**?attr/motionEasingEmphasized** | `path(M 0,0 C 0.05, 0, 0.133333, 0.06, 0.166666, 0.4 C 0.208333, 0.82, 0.25, 1, 1, 1)`<br/>`FastOutExtraSlowIn` | Easing used for elements that begin and end at rest but want extra attention drawn to the end of the animation.
1095+
**?attr/motionEasingDecelerated** | `cubic-bezier(0.0, 0.0, 0.2, 1)`<br/>`LinearOutSlowIn` | Easing used for incoming elements; motion begins at peak velocity and ends at rest.
1096+
**?attr/motionEasingAccelerated** | `cubic-bezier(0.4, 0.0, 1, 1)`<br/>`FastOutLinearIn` | Easing used for outgoing elements; motion begins at rest and ends at peak velocity.
1097+
**?attr/motionEasingLinear** | `cubic-bezier(0, 0, 1, 1)`<br/>`Linear` | Easing for simple motion such as fading.
1098+
1099+
Easing attributes are able to accept two types of curves - cubic beziers and
1100+
vector paths. Cubic bezier curves are in the standard (x1, y1, x2, y2) format.
1101+
For vector path curves, the curve must start at 0,0 and end at 1, 1. Vector path
1102+
curves can be beneficial if you’d like to introduce 3-point (quintic) easing
1103+
curves to your app in a backwards compatible way.
1104+
1105+
To update an easing value override any of the attributes in your app’s theme
1106+
following the `<type>(value)` string format.
1107+
1108+
```
1109+
<style name="Theme.MyTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
1110+
....
1111+
<item name="motionEasingEmphasized">path(M 0,0 C .25, 0, .266666, .333334, .333334, .7166664 C .366667, .9666664, .3333334, 1, 1, 1)</item>
1112+
</style>
1113+
```
1114+
1115+
For more information on easing, see
1116+
[material.io/design/motion/customization.html#applying-customizations](https://material.io/design/motion/customization.html#applying-customizations).
1117+
1118+
### Duration
1119+
1120+
Duration attributes are a set of durations in milliseconds that can be used for
1121+
animations.
1122+
1123+
Attribute | Default value | Description
1124+
-------------- | ------------------------ | ---------------------------------
1125+
**?attr/motionDurationShort1** | `75ms` | Duration for use with small motion areas such as icons and selection controls.
1126+
**?attr/motionDurationShort2** | `150ms` |
1127+
**?attr/motionDurationMedium1** | `200ms` | Duration for use with large motion areas such as bottom sheets and expanding chips.
1128+
**?attr/motionDurationMedium2** | `250ms` |
1129+
**?attr/motionDurationLong1** | `300ms` | Duration for use with elements that traverse a large portion of the screen, such as page transitions.
1130+
**?attr/motionDurationLong2** | `350ms` |
1131+
1132+
In general, durations should increase in duration as the area/traversal of an
1133+
animation increases. Maintaining this rule when customizing duration attributes
1134+
will ensure your transitions have a consistent sense of speed.
1135+
1136+
To override a duration attribute, assign the attribute to your desired
1137+
millisecond integer value.
1138+
1139+
```
1140+
<style name="Theme.MyTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar">
1141+
....
1142+
<item name="motionDurationLong2">450</item>
1143+
</style>
1144+
```
1145+
1146+
For more information on duration, see
1147+
[material.io/design/motion/customization.html#speed](https://material.io/design/motion/customization.html#speed)
1148+
1149+
### Path
1150+
1151+
Path attributes are values which control the behavior of animating elements.
1152+
1153+
Attribute | Default value | Description
1154+
-------------- | ------------------------ | ---------------------------------
1155+
**?attr/motionPath** | `linear` | An enum that controls the path along which animating elements move.<br/>`linear`: Elements move along a straight path from their current position to their new position. A linear path corresponds to a `null` `PathMotion`.<br/>`arc`: Elements move along a curved/arced path. An arc path corresponds to a `MaterialArcMotion` `PathMotion`.
1156+
1157+
For more information of motionPath, see
1158+
[material.io/design/motion/customization.html#motion-paths](https://material.io/design/motion/customization.html#motion-paths)

0 commit comments

Comments
 (0)