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

   1 ## Introduction
   2
   3 The Material Design Lite (MDL) **menu** component is a user interface element that allows users to select one of a number of options. The selection typically results in an action initiation, a setting change, or other observable effect. Menu options are always presented in sets of two or more, and options may be programmatically enabled or disabled as required. The menu appears when the user is asked to choose among a series of options, and is usually dismissed after the choice is made.
   4
   5 Menus are an established but non-standardized feature in user interfaces, and allow users to make choices that direct the activity, progress, or characteristics of software. Their design and use is an important factor in the overall user experience. See the menu component's [Material Design specifications page](http://www.google.com/design/spec/components/menus.html) for details.
   6
   7 ### To include an MDL **menu** component:
   8
   9 > **Note:** The menu requires a non-static positioned parent element. Positioning options may not work properly if the menu is inside of a statically positioned node.
  10
  11 &nbsp;1. Code a `<button>` element; this is the clickable toggle that will show and hide the menu options. Include an `id` attribute whose value will match the `for` (or `data-mdl-for`) attribute of the unordered list coded in the next step. Inside the button, code a `<i>` or `<span>` element to contain an icon of your choice.
  12 ```html
  13 <button id="menu1">
  14   <i></i>
  15 </button>
  16 ```
  17 &nbsp;2. Code a `<ul>` unordered list element; this is the container that holds the options. Include a `for` attribute whose value matches the `id` attribute of the button element.
  18 ```html
  19 <ul for="menu1">
  20 </ul>
  21 ```
  22 &nbsp;3. Inside the unordered list, code one `<li>` element for each option. Include any desired attributes and values, such as an id or event handler, and add a text caption as appropriate.
  23 ```html
  24 <ul for="menu1">
  25   <li>Continue</li>
  26   <li>Stop</li>
  27   <li>Pause</li>
  28 </ul>
  29 ```
  30 &nbsp;4. Add one or more MDL classes, separated by spaces, to the button and span elements using the `class` attribute.
  31 ```html
  32 <button id="menu1" class="mdl-button mdl-js-button mdl-button--icon">
  33   <i class="material-icons">more_vert</i>
  34 </button>
  35 ```
  36 &nbsp;5. Add one or more MDL classes, separated by spaces, to the unordered list and the list items using the `class` attribute.
  37 ```html
  38 <ul class="mdl-menu mdl-js-menu" for="menu1">
  39   <li class="mdl-menu__item">Continue</li>
  40   <li class="mdl-menu__item">Stop</li>
  41   <li class="mdl-menu__item">Pause</li>
  42 </ul>
  43 ```
  44
  45 The menu component is ready for use.
  46
  47 #### Examples
  48
  49 A menu with three options.
  50 ```html
  51 <button id="menu-speed" class="mdl-button mdl-js-button mdl-button--icon">
  52   <i class="material-icons">more_vert</i>
  53 </button>
  54 <ul class="mdl-menu mdl-js-menu" for="menu-speed">
  55   <li class="mdl-menu__item">Fast</li>
  56   <li class="mdl-menu__item">Medium</li>
  57   <li class="mdl-menu__item">Slow</li>
  58 </ul>
  59 ```
  60 A menu with three options, with ripple effect on button and option links.
  61 ```html
  62 <button id="menu-speed" class="mdl-button mdl-js-button mdl-button--icon">
  63   <i class="material-icons">more_vert</i>
  64 </button>
  65 <ul class="mdl-menu mdl-js-menu mdl-js-ripple-effect" for="menu-speed">
  66   <li class="mdl-menu__item">Fast</li>
  67   <li class="mdl-menu__item">Medium</li>
  68   <li class="mdl-menu__item">Slow</li>
  69 </ul>
  70 ```
  71 A menu with three options, the second of which is disabled by default.
  72 ```html
  73 <button id="menu-speed" class="mdl-button mdl-js-button mdl-button--icon">
  74   <i class="material-icons">more_vert</i>
  75 </button>
  76 <ul class="mdl-menu mdl-js-menu" for="menu-speed">
  77   <li class="mdl-menu__item">Fast</li>
  78   <li class="mdl-menu__item" disabled>Medium</li>
  79   <li class="mdl-menu__item">Slow</li>
  80 </ul>
  81 ```
  82
  83 ## Configuration options
  84
  85 The MDL CSS classes apply various predefined visual and behavioral enhancements to the menu. The table below lists the available classes and their effects.
  86
  87 | MDL class | Effect | Remarks |
  88 |-----------|--------|---------|
  89 | `mdl-button` | Defines button as an MDL component | Required on button element |
  90 | `mdl-js-button` | Assigns basic MDL behavior to button | Required on button element |
  91 | `mdl-button--icon` | Applies *icon* (small plain circular) display effect to button | Required on button element |
  92 | `material-icons` | Defines span as a material icon | Required on an inline element |
  93 | `mdl-menu` | Defines an unordered list container as an MDL component | Required on ul element |
  94 | `mdl-js-menu` | Assigns basic MDL behavior to menu | Required on ul element |
  95 | `mdl-menu__item` | Defines buttons as MDL menu options and assigns basic MDL behavior | Required on list item elements |
  96 | `mdl-menu__item--full-bleed-divider` | Modifies an item to have a full bleed divider between it and the next list item. | Optional on list item elements |
  97 | `mdl-js-ripple-effect` | Applies *ripple* click effect to option links | Optional; goes on unordered list element |
  98 | `mdl-menu--top-left` | Positions menu above button, aligns left edge of menu with button  | Optional; goes on unordered list element |
  99 | (none) | Positions menu below button, aligns left edge of menu with button | Default |
 100 | `mdl-menu--top-right` | Positions menu above button, aligns right edge of menu with button | Optional; goes on unordered list element |
 101 | `mdl-menu--bottom-right` | Positions menu below button, aligns right edge of menu with button | Optional; goes on unordered list element |
 102
 103 (1) The "more-vert" icon class is used here as an example. Other icons can be used by modifying the class name. For a list of available icons, see [this page](http://google.github.io/web-starter-kit/latest/styleguide/icons/demo.html); hover over an icon to see its class name.
 104
 105 (2) The `i` or `span` element in "button"" element can be used interchangeably.
 106
 107 >**Note:** Disabled versions of the menu options are provided, and are invoked with the standard HTML boolean attribute `disabled` or `data-mdl-disabled`. `<li class="mdl-menu__item" disabled>Medium</li>`
 108 >This attribute may be added or removed programmatically via scripting.