third_party/ot-br-posix/repo/third_party/mdl/repo/src/switch/README.md

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **switch** component is an enhanced version of the standard HTML `<input type="checkbox">` element. A switch consists of a short horizontal "track" with a prominent circular state indicator and, typically, text that clearly communicates a binary condition that will be set or unset when the user clicks or touches it. Like checkboxes, switches may appear individually or in groups, and can be selected and deselected individually. However, switches provide a more intuitive visual representation of their state: left/gray for *off*, right/colored for *on*. The MDL switch component allows you to add both display and click effects.
   4
   5 Switches, particularly as a replacement for certain checkboxes, can be a valuable feature in user interfaces, regardless of a site's content or function. Their design and use is therefore an important factor in the overall user experience. See the switch component's [Material Design specifications page](http://www.google.com/design/spec/components/selection-controls.html#selection-controls-switch) for details.
   6
   7 The enhanced switch component has a more vivid visual look than a standard checkbox, and may be initially or programmatically *disabled*.
   8
   9 ### To include an MDL **switch** component:
  10
  11 &nbsp;1. Code a `<label>` element and give it a `for` attribute whose value is the unique id of the switch it will contain.
  12 ```html
  13 <label for="switch1">
  14 ...
  15 </label>
  16 ```
  17 &nbsp;2. Inside the label, code an `<input>` element and give it a `type` attribute whose value is `"checkbox"`. Also give it an `id` attribute whose value matches the label's `for` attribute value.
  18 ```html
  19 <label for="switch1">
  20   <input type="checkbox" id="switch1">
  21 </label>
  22 ```
  23 &nbsp;3. Also inside the label, after the checkbox, code a `<span>` element containing the switch's text caption.
  24 ```html
  25 <label for="switch1">
  26   <input type="checkbox" id="switch1">
  27   <span>Sound off/on</span>
  28 </label>
  29 ```
  30 &nbsp;4. Add one or more MDL classes, separated by spaces, to the label, switch, and caption using the `class` attribute.
  31 ```html
  32 <label for="switch1" class="mdl-switch mdl-js-switch">
  33   <input type="checkbox" id="switch1" class="mdl-switch__input">
  34   <span class="mdl-switch__label">Sound off/on</span>
  35 </label>
  36 ```
  37
  38 The switch component is ready for use.
  39
  40 #### Example
  41
  42 A switch with a ripple click effect.
  43
  44 ```html
  45 <label for="switch1" class="mdl-switch mdl-js-switch mdl-js-ripple-effect">
  46   <input type="checkbox" id="switch1" class="mdl-switch__input">
  47   <span class="mdl-switch__label">Sound off/on</span>
  48 </label>
  49 ```
  50
  51 ## Configuration options
  52
  53 The MDL CSS classes apply various predefined visual and behavioral enhancements to the switch. The table below lists the available classes and their effects.
  54
  55 | MDL class | Effect | Remarks |
  56 |-----------|--------|---------|
  57 | `mdl-switch` | Defines label as an MDL component | Required on label element|
  58 | `mdl-js-switch` | Assigns basic MDL behavior to label | Required on label element |
  59 | `mdl-switch__input` | Applies basic MDL behavior to switch | Required on input element (switch) |
  60 | `mdl-switch__label` | Applies basic MDL behavior to caption | Required on span element (caption) |
  61 | `mdl-js-ripple-effect` | Applies *ripple* click effect | Optional; goes on label element, not input element (switch) |
  62
  63 >**Note:** Disabled versions of all available switch types are provided, and are invoked with the standard HTML boolean attribute `disabled`. `<input type="checkbox" id="switch5" class="mdl-switch__input" disabled>`
  64 >This attribute may be added or removed programmatically via scripting.