1page.title=Selection 2page.tags=actionmode,navigation,contextual 3@jd:body 4 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 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 13handle 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 22actions 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 24contextual actions and selection management functions for selected data into a new element called 25the 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</h4> 39<p itemprop="description">The contextual action bar (CAB) is a temporary action bar that overlays your app's current action bar while data 40is 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 71pattern</a> to decide which items to surface at the top level and which to move to the 72action 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 75the selection. Actions that apply to a single selected data item don't necessarily apply to multiple 76selected 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 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 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> 115
