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