Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 1 | page.title=Selection |
Scott Main | 64d5103 | 2013-04-12 14:00:30 -0700 | [diff] [blame] | 2 | page.tags="actionmode","navigation","contextual" |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 3 | @jd:body |
| 4 | |
Scott Main | cbcd17d | 2013-05-14 08:46:55 -0700 | [diff] [blame] | 5 | <a class="notice-developers" href="{@docRoot}guide/topics/ui/menus.html#context-menu"> |
| 6 | <div> |
| 7 | <h3>Developer Docs</h3> |
| 8 | <p>Menus: Creating Contextual Menus</p> |
| 9 | </div> |
| 10 | </a> |
| 11 | |
Peter Ng | 0212363 | 2012-08-06 11:44:48 -0700 | [diff] [blame] | 12 | <p>Android 3.0 changed the <em>long press</em> gesture—that is, a touch that's held in the same position for a moment—to be the global gesture to select data.. This affects the way you should |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 13 | handle multi-select and contextual actions in your apps.</p> |
| 14 | |
| 15 | <div class="vspace size-1"> </div> |
| 16 | |
| 17 | <div class="layout-content-row"> |
| 18 | <div class="layout-content-col span-6"> |
| 19 | |
| 20 | <h4>What has changed?</h4> |
| 21 | <p>In previous versions of Android, the long press gesture was universally used to display contextual |
| 22 | actions for a given data item in a contextual menu.</p> |
| 23 | <p>This pattern changed with Android 3.0. The long press gesture is now used to select data, combining |
| 24 | contextual actions and selection management functions for selected data into a new element called |
| 25 | the contextual action bar (CAB).</p> |
| 26 | |
| 27 | </div> |
| 28 | <div class="layout-content-col span-7"> |
| 29 | |
| 30 | <img src="{@docRoot}design/media/selection_context_menu.png"> |
| 31 | <div class="figure-caption"> |
| 32 | Traditional use of the long press gesture to show contextual menus. |
| 33 | </div> |
| 34 | |
| 35 | </div> |
| 36 | </div> |
| 37 | |
| 38 | <h4>Using the contextual action bar (CAB)</h4> |
| 39 | <p>The selection CAB is a temporary action bar that overlays your app's current action bar while data |
| 40 | is selected. It appears after the user long presses on a selectable data item.</p> |
| 41 | |
| 42 | <img src="{@docRoot}design/media/selection_cab_big.png"> |
| 43 | |
| 44 | <div class="vspace size-1"> </div> |
| 45 | |
| 46 | <div class="layout-content-row"> |
| 47 | <div class="layout-content-col span-6"> |
| 48 | |
| 49 | <p>From here the user can:</p> |
| 50 | <ul> |
| 51 | <li>Select additional data items by touching them.</li> |
| 52 | <li>Trigger an action from the CAB that applies to all highlighted data items. The CAB then |
| 53 | automatically dismisses itself.</li> |
| 54 | <li>Dismiss the CAB via the navigation bar's Back button or the CAB's checkmark button. This removes |
| 55 | the CAB along with all selection highlights.</li> |
| 56 | </ul> |
| 57 | |
| 58 | </div> |
| 59 | <div class="layout-content-col span-7"> |
| 60 | |
| 61 | <img src="{@docRoot}design/media/selection_cab_example.png"> |
| 62 | |
| 63 | </div> |
| 64 | </div> |
| 65 | |
| 66 | <div class="layout-content-row"> |
| 67 | <div class="layout-content-col span-6"> |
| 68 | |
| 69 | <h4>Selecting CAB actions</h4> |
| 70 | <p>You can decide which actions and elements appear in the CAB. Use the guidelines in the <a href="actionbar.html">Action Bar |
| 71 | pattern</a> to decide which items to surface at the top level and which to move to the |
| 72 | action overflow.</p> |
| 73 | <h4>Dynamically adjust CAB actions</h4> |
| 74 | <p>In most cases you need to adjust the actions in the CAB dynamically as the user adds more items to |
| 75 | the selection. Actions that apply to a single selected data item don't necessarily apply to multiple |
| 76 | selected data items of the same kind.</p> |
| 77 | |
| 78 | </div> |
| 79 | <div class="layout-content-col span-7"> |
| 80 | |
| 81 | <img src="{@docRoot}design/media/selection_adjusting_actions.png"> |
| 82 | <div class="figure-caption"> |
| 83 | Adjusting actions in the CAB as additional items are selected. |
| 84 | </div> |
| 85 | |
| 86 | </div> |
| 87 | </div> |
| 88 | |
Scott Main | 2ed01ad | 2012-10-04 11:14:01 -0700 | [diff] [blame] | 89 | <div class="note develop"> |
| 90 | <p><strong>Developer Guide</strong></p> |
| 91 | <p>For information about how to create a contextual action bar, read |
| 92 | <a href="{@docRoot}guide/topics/ui/menus.html#CAB">Using the contextual action mode</a>.</p> |
| 93 | </div> |
| 94 | |
| 95 | |
Roman Nurik | b99ae73 | 2012-03-06 12:26:15 -0800 | [diff] [blame] | 96 | <h2 id="checklist">Checklist</h2> |
| 97 | |
| 98 | <ul> |
| 99 | <li> |
| 100 | <p>Whenever your app supports the selection of multiple data items, make use of the contextual action |
| 101 | bar (CAB).</p> |
| 102 | </li> |
| 103 | <li> |
| 104 | <p>Reserve the long press gesture for selection exclusively. Don't use it to display traditional |
| 105 | contextual menus.</p> |
| 106 | </li> |
| 107 | <li> |
| 108 | <p>If you don't support multi-selection within a list, long press should do nothing.</p> |
| 109 | </li> |
| 110 | <li> |
| 111 | <p>Plan the actions you want to display inside of a CAB in the same way you would plan the actions |
| 112 | inside your app's action bar.</p> |
| 113 | </li> |
| 114 | </ul> |