diff --git a/docs/components/Switch.md b/docs/components/Switch.md index a1785d872dc..b2a9316d128 100644 --- a/docs/components/Switch.md +++ b/docs/components/Switch.md @@ -31,7 +31,7 @@ Material Components for Android library. For more information, go to the [Getting started](https://github.com/material-components/material-components-android/tree/master/docs/getting-started.md) page. -**Note:** The `SwitchMaterial` widget provides a complete implementation of +**Note:** The `MaterialSwitch` widget provides a complete implementation of Material Design's switch component. It extends from the support library's `SwitchCompat` widget, but not from the framework `Switch` widget. As such, it does not auto-inflate, unlike other selection controls, and must be explicitly @@ -56,8 +56,193 @@ often used on mobile devices to enable and disable options in an options menu. A switch consists of a track and thumb; the thumb moves along the track to indicate its current state. +**Note:** Since version 1.7.0, the new `MaterialSwitch` class will replace the +obsolete `SwitchMaterial` class. In most cases you should be able to just +replace all `SwitchMaterial` class reference with `MaterialSwitch` to enjoy the +default look and feel. Please refer to the following sections if you need to +customize the new styles. + +**Note:** For the old `SwitchMaterial` documentation, please refer to +[Switch (deprecated)](#switch-deprecated) and +[Theming switches (deprecated)](#theming-switches-deprecated). + ### Switches example +The following example shows a list of five switches. + +![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example.png) + +In the layout: + +```xml + + + + + +``` + +In code: + +```kt +// To check a switch +materialSwitch.isChecked = true + +// To listen for a switch's checked/unchecked state changes +materialSwitch.setOnCheckedChangeListener { buttonView, isChecked + // Responds to switch being checked/unchecked +} +``` + +## Anatomy and key properties + +The following is an anatomy diagram that shows a switch thumb and a switch +track: + +![Switch anatomy diagram](assets/switch/switch_anatomy.png) + +1. Thumb +2. Track +3. Icon (optional) + +### Switch attributes + +Element | Attribute | Related method(s) | Default value +-------------- | ------------------- | --------------------------------- | ------------- +**Min height** | `android:minHeight` | `setMinHeight`
`getMinHeight` | `?attr/minTouchTargetSize` + +### Thumb attributes + +Element | Attribute | Related method(s) | Default value +--------- | --------------- | ----------------------------------------- | ------------- +**Thumb** | `android:thumb` | `setThumbDrawable`
`getThumbDrawable` | `@drawable/mtrl_switch_thumb` +**Color** | `app:thumbTint` | `setThumbTintList`
`getThumbTintList` | `?attr/colorOutline` (unchecked)
`?attr/colorOnPrimary` (checked) + +### Icon attributes + +Element | Attribute | Related method(s) | Default value +--------- | ------------------- | ------------------------------------------------- | ------------- +**Icon** | `app:thumbIcon` | `setThumbIconDrawable`
`getThumbIconDrawable` | `null` +**Color** | `app:thumbIconTint` | `setThumbIconTintList`
`getThumbIconTintList` | `?attr/colorSurfaceVariant` (unchecked)
`?attr/colorOnPrimaryContainer` (checked) + +You can add an optional icon to enhance the on/off indication of your custom +switch by assiging `app:thumbIcon`. This icon will be centered and displayed on +top of the thumb drawable. + +### Track attributes + +Element | Attribute | Related method(s) | Default value +-------------------- | ------------------------- | ------------------------------------------------------------- | ------------- +**Track** | `app:track` | `setTrackDrawable`
`getTrackDrawable` | `@drawable/mtrl_switch_track` +**Color** | `app:trackTint` | `setTrackTintList`
`getTrackTintList` | `?attr/colorSurfaceVariant` (unchecked)
`?attr/colorPrimary` (checked) +**Decoration** | `app:trackDecoration` | `setTrackDecorationDrawable`
`getTrackDecorationDrawable` | `@drawable/mtrl_switch_track_decoration`
(Shows an outline of the track.) +**Decoration color** | `app:trackDecorationTint` | `setTrackDecorationTintList`
`getTrackDecorationTintList` | `?attr/colorOutline` (unchecked)
`@android:color/transparent` (checked) + +### Text label attributes + +Element | Attribute | Related method(s) | Default value +-------------- | ------------------------ | ----------------------------------------- | ------------- +**Text label** | `android:text` | `setText`
`getText` | `null` +**Color** | `android:textColor` | `setTextColor`
`getTextColors` | `?android:attr/textColorPrimaryDisableOnly` +**Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceBodyMedium` +**Padding** | `app:switchPadding` | `setSwitchPadding`
`getSwitchPadding` | `16dp` + +### Switch states + +Switches can be on or off. Switches have enabled, hover, focused, and pressed +states. + +![Switch states in an array. Columns are enabled, disabled, hover, focused, +pressed. Rows are on or off](assets/switch/switch_states.png) + +### Styles + +Element | Style +----------------- | ------------------------------------------------ +**Default style** | `Widget.Material3.CompoundButton.MaterialSwitch` + +Default style theme attribute: `?attr/materialSwitchStyle` + +See the full list of +[styles](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/materialswitch/res/values/styles.xml) +and +[attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/materialswitch/res/values/attrs.xml). + +## Theming switches + +Switches support +[Material Theming](https://material.io/components/selection-controls#theming), +which can customize color and typography. + +### Switch theming example + +The following example shows a list of switches with Material Theming. + +!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming.png) + +#### Implementing switch theming + +Use theme attributes in `res/values/styles.xml`, which applies to all switches +and affects other components: + +```xml + + +``` + +Use default style theme attributes, styles and theme overlays, which apply to +all switches but do not affect other components: + +```xml + + + + + +``` + +Use the styles in the layout, which affects only this switch: + +```xml + +``` + +## Switch (deprecated) + +### Switches example (deprecated) + API and source code: * `SwitchMaterial` @@ -66,7 +251,7 @@ API and source code: The following example shows a list of five switches. -![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example.png) +![Example of 5 switches, the first one is toggled and the last one is disabled.](assets/switch/switch_example_deprecated.png) In the layout: @@ -99,25 +284,25 @@ In code: ```kt // To check a switch -switchMaterial.isChecked = true +switchmaterial.isChecked = true // To listen for a switch's checked/unchecked state changes -switchMaterial.setOnCheckedChangeListener { buttonView, isChecked +switchmaterial.setOnCheckedChangeListener { buttonView, isChecked // Responds to switch being checked/unchecked } ``` -## Anatomy and key properties +## Anatomy and key properties (deprecated) The following is an anatomy diagram that shows a switch thumb and a switch track: -![Switch anatomy diagram](assets/switch/switch_anatomy.png) +![Switch anatomy diagram](assets/switch/switch_anatomy_deprecated.png) 1. Thumb 2. Track -### Switch attributes +### Switch attributes (deprecated) Element | Attribute | Related method(s) | Default value -------------------------- | ------------------------------------------ | ---------------------------------------------------------- | ------------- @@ -137,7 +322,7 @@ with a custom drawable that should not be tinted, set /> ``` -### Thumb attributes +### Thumb attributes (deprecated) Element | Attribute | Related method(s) | Default value ------------- | --------------- | ----------------------------------------- | ------------- @@ -145,14 +330,14 @@ Element | Attribute | Related method(s) | De **Color** | `app:thumbTint` | `setThumbTintList`
`getThumbTintList` | `?attr/colorOnSurface` (unchecked)
`?attr/colorPrimary` (checked) **Elevation** | N/A | N/A | `4dp` -### Track attributes +### Track attributes (deprecated) Element | Attribute | Related method(s) | Default value --------- | --------------- | ----------------------------------------- | ------------- **Track** | `app:track` | `setTrackDrawable`
`getTrackDrawable` | inherits from `SwitchCompat` **Color** | `app:trackTint` | `setTrackTintList`
`getTrackTintList` | `?attr/colorOutline` (unchecked)
`?attr/colorPrimaryContainer` (checked) -### Text label attributes +### Text label attributes (deprecated) Element | Attribute | Related method(s) | Default value -------------- | ------------------------ | ---------------------------------- | ------------- @@ -160,7 +345,7 @@ Element | Attribute | Related method(s) | **Color** | `android:textColor` | `setTextColor`
`getTextColors` | `?android:attr/textColorPrimaryDisableOnly` **Typography** | `android:textAppearance` | `setTextAppearance` | `?attr/textAppearanceBodyMedium` -### Switch states +### Switch states (deprecated) Switches can be on or off. Switches have enabled, hover, focused, and pressed states. @@ -171,9 +356,9 @@ interaction may obstruct the element completely. For desktop, the radial reaction isn't needed. ![Switch states in an array. Columns are enabled, disabled, hover, focused, -pressed. Rows are on or off](assets/switch/switch_states.png) +pressed. Rows are on or off](assets/switch/switch_states_deprecated.png) -### Styles +### Styles (deprecated) Element | Style ----------------- | ---------------------------------------- @@ -186,13 +371,13 @@ See the full list of and [attrs](https://github.com/material-components/material-components-android/tree/master/lib/java/com/google/android/material/switchmaterial/res/values/attrs.xml). -## Theming switches +## Theming switches (deprecated) Switches support [Material Theming](https://material.io/components/selection-controls#theming), which can customize color and typography. -### Switch theming example +### Switch theming example (deprecated) API and source code: @@ -202,9 +387,9 @@ API and source code: The following example shows a list of switches with Material Theming. -!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming.png) +!["5 switches with brown text: first switch is on and has pink thumb and track"](assets/switch/switch_theming_deprecated.png) -#### Implementing switch theming +#### Implementing switch theming (deprecated) Use theme attributes in `res/values/styles.xml`, which applies to all switches and affects other components: diff --git a/docs/components/assets/switch/switch_anatomy.png b/docs/components/assets/switch/switch_anatomy.png index 0605b251a71..39cc16ae2c2 100644 Binary files a/docs/components/assets/switch/switch_anatomy.png and b/docs/components/assets/switch/switch_anatomy.png differ diff --git a/docs/components/assets/switch/switch_anatomy_deprecated.png b/docs/components/assets/switch/switch_anatomy_deprecated.png new file mode 100644 index 00000000000..0605b251a71 Binary files /dev/null and b/docs/components/assets/switch/switch_anatomy_deprecated.png differ diff --git a/docs/components/assets/switch/switch_example.png b/docs/components/assets/switch/switch_example.png index 6e696efa950..69d2252b198 100644 Binary files a/docs/components/assets/switch/switch_example.png and b/docs/components/assets/switch/switch_example.png differ diff --git a/docs/components/assets/switch/switch_example_deprecated.png b/docs/components/assets/switch/switch_example_deprecated.png new file mode 100644 index 00000000000..6e696efa950 Binary files /dev/null and b/docs/components/assets/switch/switch_example_deprecated.png differ diff --git a/docs/components/assets/switch/switch_hero.png b/docs/components/assets/switch/switch_hero.png index 018a4572aed..ab95ffc123b 100644 Binary files a/docs/components/assets/switch/switch_hero.png and b/docs/components/assets/switch/switch_hero.png differ diff --git a/docs/components/assets/switch/switch_hero_deprecated.png b/docs/components/assets/switch/switch_hero_deprecated.png new file mode 100644 index 00000000000..018a4572aed Binary files /dev/null and b/docs/components/assets/switch/switch_hero_deprecated.png differ diff --git a/docs/components/assets/switch/switch_states.png b/docs/components/assets/switch/switch_states.png index b3166533891..94c3d4b7fc1 100644 Binary files a/docs/components/assets/switch/switch_states.png and b/docs/components/assets/switch/switch_states.png differ diff --git a/docs/components/assets/switch/switch_states_deprecated.png b/docs/components/assets/switch/switch_states_deprecated.png new file mode 100644 index 00000000000..b3166533891 Binary files /dev/null and b/docs/components/assets/switch/switch_states_deprecated.png differ diff --git a/docs/components/assets/switch/switch_theming.png b/docs/components/assets/switch/switch_theming.png index 83c72766317..a15b4f5631e 100644 Binary files a/docs/components/assets/switch/switch_theming.png and b/docs/components/assets/switch/switch_theming.png differ diff --git a/docs/components/assets/switch/switch_theming_deprecated.png b/docs/components/assets/switch/switch_theming_deprecated.png new file mode 100644 index 00000000000..83c72766317 Binary files /dev/null and b/docs/components/assets/switch/switch_theming_deprecated.png differ