[Switch] Update dev doc with the new switch design

PiperOrigin-RevId: 463922188

Author: drchen

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
+<com.google.android.material.materialswitch.MaterialSwitch
+    android:layout_width="wrap_content"
+    android:layout_height="match_parent"
+    android:checked="true"
+    android:text="@string/label_1"/>
+<com.google.android.material.materialswitch.MaterialSwitch
+    android:layout_width="wrap_content"
+    android:layout_height="match_parent"
+    android:text="@string/label_2"/>
+<com.google.android.material.materialswitch.MaterialSwitch
+    android:layout_width="wrap_content"
+    android:layout_height="match_parent"
+    android:text="@string/label_3"/>
+<com.google.android.material.materialswitch.MaterialSwitch
+    android:layout_width="wrap_content"
+    android:layout_height="match_parent"
+    android:text="@string/label_4"/>
+<com.google.android.material.materialswitch.MaterialSwitch
+    android:layout_width="wrap_content"
+    android:layout_height="match_parent"
+    android:enabled="false"
+    android:text="@string/label_5"/>
+```
+
+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`<br/>`getMinHeight` | `?attr/minTouchTargetSize`
+
+### Thumb attributes
+
+Element   | Attribute       | Related method(s)                         | Default value
+--------- | --------------- | ----------------------------------------- | -------------
+**Thumb** | `android:thumb` | `setThumbDrawable`<br/>`getThumbDrawable` | `@drawable/mtrl_switch_thumb`
+**Color** | `app:thumbTint` | `setThumbTintList`<br/>`getThumbTintList` | `?attr/colorOutline` (unchecked)<br/>`?attr/colorOnPrimary` (checked)
+
+### Icon attributes
+
+Element   | Attribute           | Related method(s)                                 | Default value
+--------- | ------------------- | ------------------------------------------------- | -------------
+**Icon**  | `app:thumbIcon`     | `setThumbIconDrawable`<br/>`getThumbIconDrawable` | `null`
+**Color** | `app:thumbIconTint` | `setThumbIconTintList`<br/>`getThumbIconTintList` | `?attr/colorSurfaceVariant` (unchecked)<br/>`?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`<br/>`getTrackDrawable`                     | `@drawable/mtrl_switch_track`
+**Color**            | `app:trackTint`           | `setTrackTintList`<br/>`getTrackTintList`                     | `?attr/colorSurfaceVariant` (unchecked)<br/>`?attr/colorPrimary` (checked)
+**Decoration**       | `app:trackDecoration`     | `setTrackDecorationDrawable`<br/>`getTrackDecorationDrawable` | `@drawable/mtrl_switch_track_decoration`<br/>(Shows an outline of the track.)
+**Decoration color** | `app:trackDecorationTint` | `setTrackDecorationTintList`<br/>`getTrackDecorationTintList` | `?attr/colorOutline` (unchecked)<br/>`@android:color/transparent` (checked)
+
+### Text label attributes
+
+Element        | Attribute                | Related method(s)                         | Default value
+-------------- | ------------------------ | ----------------------------------------- | -------------
+**Text label** | `android:text`           | `setText`<br/>`getText`                   | `null`
+**Color**      | `android:textColor`      | `setTextColor`<br/>`getTextColors`        | `?android:attr/textColorPrimaryDisableOnly`
+**Typography** | `android:textAppearance` | `setTextAppearance`                       | `?attr/textAppearanceBodyMedium`
+**Padding**    | `app:switchPadding`      | `setSwitchPadding`<br/>`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
+<style name="Theme.App" parent="Theme.Material3.*">
+    ...
+    <item name="colorPrimary">@color/pink_200</item>
+    <item name="colorSurfaceVariant">@color/pink_100</item>
+</style>
+
+```
+
+Use default style theme attributes, styles and theme overlays, which apply to
+all switches but do not affect other components:
+
+```xml
+<style name="Theme.App" parent="Theme.Material3.*">
+    ...
+    <item name="materialSwitchStyle">@style/Widget.App.Switch</item>
+</style>
+
+<style name="Widget.App.Switch" parent="Widget.Material3.CompoundButton.MaterialSwitch">
+    <item name="materialThemeOverlay">@style/ThemeOverlay.App.Switch</item>
+</style>
+
+<style name="ThemeOverlay.App.Switch" parent="">
+    <item name="colorPrimary">@color/pink_200</item>
+    <item name="colorSurfaceVariant">@color/pink_100</item>
+</style>
+```
+
+Use the styles in the layout, which affects only this switch:
+
+```xml
+<com.google.android.material.materialswitch.MaterialSwitch
+        ...
+    style="@style/Widget.App.Switch"
+    />
+```
+
+## 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,30 +322,30 @@ with a custom drawable that should not be tinted, set
     />
 ```
 
-### Thumb attributes
+### Thumb attributes (deprecated)
 
 Element       | Attribute       | Related method(s)                         | Default value
 ------------- | --------------- | ----------------------------------------- | -------------
 **Thumb**     | `android:thumb` | `setThumbDrawable`<br/>`getThumbDrawable` | inherits from `SwitchCompat`
 **Color**     | `app:thumbTint` | `setThumbTintList`<br/>`getThumbTintList` | `?attr/colorOnSurface` (unchecked)<br/>`?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`<br/>`getTrackDrawable` | inherits from `SwitchCompat`
 **Color** | `app:trackTint` | `setTrackTintList`<br/>`getTrackTintList` | `?attr/colorOutline` (unchecked)<br/>`?attr/colorPrimaryContainer` (checked)
 
-### Text label attributes
+### Text label attributes (deprecated)
 
 Element        | Attribute                | Related method(s)                  | Default value
 -------------- | ------------------------ | ---------------------------------- | -------------
 **Text label** | `android:text`           | `setText`<br/>`getText`            | `null`
 **Color**      | `android:textColor`      | `setTextColor`<br/>`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: