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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
|
page.title=Action Bar
parent.title=User Interface
parent.link=index.html
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>A title bar that includes the application icon and activity title</li>
<li>Provides access to menu items and navigation modes such as tabs</li>
<li>Requires API level 11 or greater</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#Adding">Adding the Action Bar</a>
<ol>
<li><a href="#Removing">Removing the action bar</a></li>
</ol>
</li>
<li><a href="#ActionItems">Adding Action Items</a>
<ol>
<li><a href="#ChoosingActionItems">Choosing your action items</a></li>
<li><a href="#SplitBar">Using split action bar</a></li>
</ol>
</li>
<li><a href="#Home">Using the App Icon for Navigation</a>
<ol>
<li><a href="#Up">Navigating up</a></li>
</ol>
</li>
<li><a href="#ActionView">Adding an Action View</a>
<ol>
<li><a href="#ActionViewCollapsing">Handling collapsible action views</a></li>
</ol>
</li>
<li><a href="#ActionProvider">Adding an Action Provider</a>
<ol>
<li><a href="#ShareActionProvider">Using the ShareActionProvider</a></li>
<li><a href="#CreatingActionProvider">Creating a custom action provider</a></li>
</ol>
</li>
<li><a href="#Tabs">Adding Navigation Tabs</a></li>
<li><a href="#Dropdown">Adding Drop-down Navigation</a></li>
<li><a href="#Style">Styling the Action Bar</a>
<ol>
<li><a href="#GeneralStyles">General appearance</a></li>
<li><a href="#ActionItemStyles">Action items</a></li>
<li><a href="#NavigationStyles">Navigation tabs</a></li>
<li><a href="#DropDownStyles">Drop-down lists</a></li>
<li><a href="#AdvancedStyles">Advanced styling</a></li>
</ol>
</li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.ActionBar}</li>
<li>{@link android.view.Menu}</li>
<li>{@link android.view.ActionProvider}</li>
</ol>
<h2>Related samples</h2>
<ol>
<li><a
href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a></li>
<li><a
href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a></li>
<li><a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/index.html#ActionBar">
API Demos</a></li>
</ol>
<h2>See also</h2>
<ol>
<li><a
href="{@docRoot}design/patterns/actionbar.html">Android Design: Action Bar</a></li>
<li><a href="{@docRoot}guide/topics/ui/menus.html">Menus</a></li>
<li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets
and Handsets</a></li>
</ol>
</div>
</div>
<p>The action bar is a window feature that identifies the application and user location, and
provides user actions and navigation modes. You should use the action bar in most activities that
need to prominently present user actions or global navigation, because the action bar offers users a
consistent interface across applications and the system gracefully adapts the action bar's
appearance for different screen configurations. You can control the behaviors and visibility of the
action bar with the {@link android.app.ActionBar} APIs, which were added in Android 3.0 (API level
11).</p>
<p>The primary goals of the action bar are to:</p>
<ul>
<li>Provide a dedicated space for identifying the application brand and user location.
<p>This is accomplished with the app icon or logo on the left side and the activity title.
You might choose to remove the activity title, however, if the current view is identified by a
navigation label, such as the currently selected tab.</p></li>
<li>Provide consistent navigation and view refinement across different applications.
<p>The action bar provides built-in tab navigation for switching between <a
href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>. It also offers a drop-down
list you can use as an alternative navigation mode or to refine the current view (such as to sort
a list by different criteria).</p>
</li>
<li>Make key actions for the activity (such as "search", "create", "share", etc.) prominent and
accessible to the user in a predictable way.
<p>You can provide instant access to key user actions by placing items from the <a
href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> directly in the action bar,
as "action items." Action items can also provide an "action view," which provides an embedded
widget for even more immediate action behaviors. Menu items that are not promoted
to an action item are available in the overflow menu, revealed by either the device MENU button
(when available) or by an "overflow menu" button in the action bar (when the device does not
include a MENU button).</p>
</li>
</ul>
<img src="{@docRoot}images/ui/actionbar.png" alt="" />
<p class="img-caption"><strong>Figure 1.</strong> Action bar from the <a
href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app (on a
landscape handset), showing the logo on the left, navigation tabs, and an action item on the
right (plus the overflow menu button).</p>
<div class="design-announce">
<p><strong>Action Bar Design</strong></p>
<p>For design guidelines, read Android Design's <a
href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> guide.</p>
</div>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Remaining backward-compatible</h2>
<p>If you want to provide an action bar in your application <em>and</em> remain compatible with
versions of Android older than 3.0, you need to create the action bar in your
activity's layout (because the {@link android.app.ActionBar} class is not available on older
versions).</p>
<p>To help you, the <a
href="{@docRoot}resources/samples/ActionBarCompat/index.html">Action Bar Compatibility</a> sample
app provides an API layer and action bar layout that allows your app to use some of the {@link
android.app.ActionBar} APIs and also support older versions of Android by replacing the traditional
title bar with a custom action bar layout.</p>
</div>
</div>
<h2 id="Adding">Adding the Action Bar</h2>
<p>Beginning with Android 3.0 (API level 11), the action bar is included in all
activities that use the {@link android.R.style#Theme_Holo Theme.Holo} theme (or one of its
descendants), which is the default theme when either the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> or
<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
attribute is set to {@code "11"} or greater. For example:</p>
<pre>
<manifest ... >
<uses-sdk android:minSdkVersion="4"
<b>android:targetSdkVersion="11"</b> />
...
</manifest>
</pre>
<p>In this example, the application requires a minimum version of API Level 4 (Android 1.6), but it
also targets API level 11 (Android 3.0). This way, when the application runs on Android 3.0 or
greater, the system applies the holographic theme to each activity, and thus, each activity includes
the action bar.</p>
<p>If you want to use {@link android.app.ActionBar} APIs, such as to add navigation modes and modify
action bar styles, you should set the <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> to {@code
"11"} or greater. If you want your app
to support older versions of Android, there are ways to use a limited set of {@link
android.app.ActionBar} APIs on devices that support API level 11 or higher, while still running
on older versions. See the sidebox for information about remaining backward-compatible.</p>
<h3 id="Removing">Removing the action bar</h3>
<p>If you don't want the action bar for a particular activity, set the activity theme to
{@link android.R.style#Theme_Holo_NoActionBar Theme.Holo.NoActionBar}. For example:</p>
<pre>
<activity android:theme="@android:style/Theme.Holo.NoActionBar">
</pre>
<p>You can also hide the action bar at runtime by calling {@link android.app.ActionBar#hide}. For
example:</p>
<pre>
ActionBar actionBar = {@link android.app.Activity#getActionBar()};
actionBar.hide();
</pre>
<p>When the action bar hides, the system adjusts your activity layout to fill all the
screen space now available. You can bring the action bar back with {@link
android.app.ActionBar#show()}.</p>
<p>Beware that hiding and removing the action bar causes your activity to re-layout in order to
account for the space consumed by the action bar. If your activity regularly hides and shows the
action bar (such as in the Android Gallery app), you might want to use overlay mode. Overlay mode
draws the action bar on top of your activity layout rather than in its own area of the screen. This
way, your layout remains fixed when the action bar hides and re-appears. To enable overlay mode,
create a theme for your activity and set {@link android.R.attr#windowActionBarOverlay
android:windowActionBarOverlay} to {@code true}. For more information, see the section about <a
href="#Style">Styling the Action Bar</a>.</p>
<p class="note"><strong>Tip:</strong> If you have a custom activity theme in which you'd like to
remove the action bar, set the {@link android.R.styleable#Theme_windowActionBar
android:windowActionBar} style property to {@code false}. However, if you remove the action bar
using a theme, then the window will not allow the action bar at all, so you cannot add it
later—calling {@link android.app.Activity#getActionBar()} will return null.</p>
<h2 id="ActionItems">Adding Action Items</h2>
<p>Sometimes you might want to give users immediate access to an item from the <a
href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a>. To do this, you can
declare that the menu item should appear in the action bar as an "action item." An action item can
include an icon and/or a text title. If a menu item does not appear as an action item, then the
system places it in the overflow menu. The overflow menu is revealed either by the device MENU
button (if provided by the device) or an additional button in the action bar (if the device does not
provide the MENU button).</p>
<div class="figure" style="width:359px">
<img src="{@docRoot}images/ui/actionbar-item-withtext.png" height="57" alt="" />
<p class="img-caption"><strong>Figure 2.</strong> Two action items with icon and text titles, and
the overflow menu button.</p>
</div>
<p>When the activity first starts, the system populates the action bar and overflow menu by calling
{@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} for your activity. As
discussed in the <a href="{@docRoot}guide/topics/ui/menus.html">Menus</a> developer guide, it's in
this callback method that you should inflate an XML <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a> that defines the
menu items. For example:</p>
<pre>
@Override
public boolean onCreateOptionsMenu(Menu menu) {
MenuInflater inflater = getMenuInflater();
inflater.inflate(R.menu.main_activity, menu);
return true;
}
</pre>
<p>In the XML file, you can request a menu item to appear as an action item by declaring {@code
android:showAsAction="ifRoom"} for the {@code <item>} element. This way, the menu item appears
in the action bar for quick access only <em>if there is room</em> available. If there's not
enough room, the item appears in the overflow menu.</p>
<p>If your menu item supplies both a title and an icon—with the {@code android:title} and
{@code android:icon} attributes—then the action item shows only the icon by default. If you
want to display the text title, add {@code "withText"} to the {@code android:showAsAction}
attribute. For example:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/menu_save"
android:icon="@drawable/ic_menu_save"
android:title="@string/menu_save"
<b>android:showAsAction="ifRoom|withText"</b> />
</menu>
</pre>
<p class="note"><strong>Note:</strong> The {@code "withText"} value is a <em>hint</em> to the
action bar that the text title should appear. The action bar will show the title when possible, but
might not if an icon is available and the action bar is constrained for space.</p>
<p>When the user selects an action item, your activity receives a call to
{@link android.app.Activity#onOptionsItemSelected(MenuItem)
onOptionsItemSelected()}, passing the ID supplied by the {@code android:id} attribute—the same
callback received for all items in the options menu.</p>
<p>It's important that you always define {@code android:title} for each menu item—even if you
don't declare that the title appear with the action item—for three reasons:</p>
<ul>
<li>If there's not enough room in the action bar for the action item, the menu item appears
in the overflow menu and only the title appears.</li>
<li>Screen readers for sight-impaired users read the menu item's title.</li>
<li>If the action item appears with only the icon, a user can long-press the item to reveal a
tool-tip that displays the action item's title.</li>
</ul>
<p>The {@code android:icon} is always optional, but recommended. For icon design recommendations,
see the <a href="{@docRoot}guide/practices/ui_guidelines/icon_design_action_bar.html">Action Bar
Icon</a> design guidelines.</p>
<p class="note"><strong>Note:</strong> If you added the menu item from a fragment, via the {@link
android.app.Fragment} class's {@link android.app.Fragment#onCreateOptionsMenu onCreateOptionsMenu}
callback, then the system calls the respective {@link
android.app.Fragment#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} method for that
fragment when the user selects one of the fragment's items. However the activity gets a chance to
handle the event first, so the system calls {@link
android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()} on the activity before
calling the same callback for the fragment.</p>
<p>You can also declare an item to <em>"always"</em> appear as an action item, instead of being
placed in the overflow menu when space is limited. In most cases, you <strong>should not</strong>
force an item to appear in the action bar by using the {@code "always"} value. However, you might
need an item to always appear when it provides an <a href="#ActionView">action view</a> that does
not offer a default action for the overflow menu. Beware that too
many action items can create a cluttered UI and cause layout problems on devices with a narrow
screen. It's best to instead use {@code "ifRoom"} to request that an item appear in the action
bar, but allow the system to move it into the overflow menu when there's not enough room.</p>
<p>For more information about creating the options menu that defines your action items, see the <a
href="{@docRoot}guide/topics/ui/menus.html#options-menu">Menus</a> developer guide.</p>
<h3 id="ChoosingActionItems">Choosing your action items</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<h4>Menu items vs. other app controls</h4>
<p>As a general rule, all items in the <a
href="{@docRoot}guide/topics/ui/menus.html#OptionsMenu">options menu</a> (let alone action items)
should have a global impact on the app, rather than affect only a small portion of the interface.
For example, if you have a multi-pane layout and one pane shows a video while another lists all
videos, the video player controls should appear within the pane containing the video (not in the
action bar), while the action bar might provide action items to share the video or save the video to
a favorites list.</p>
<p>So, even before deciding whether a menu item should appear as an action item, be sure that
the item has a global scope for the current activity. If it doesn't, then you should place it
as a button in the appropriate context of the activity layout.</p>
</div>
</div>
<p>You should carefully choose which items from your options menu should appear as action items by
assessing a few key traits. In general, each action item should be <em>at least one</em>
of the following:</p>
<ol>
<li><strong>Frequently used</strong>: It's an action that your users need seven out of ten visits
or they use it several times in a row.
<p>Example frequent actions: "New message" in the Messaging app and
"Search" in Android Market.</p>
</li>
<li><strong>Important</strong>: It's an action that you need users to easily discover or, if it's
not frequently used, it's important that it be effortless to perform in the few cases that users do
need it.
<p>Example important actions: "Add network" in Wi-Fi settings and "Switch to camera" in the
Gallery app.</p>
</li>
<li><strong>Typical</strong>: It's an action that is typically provided in the action bar in
similar apps, so your users expect to find it in yours.
<p>Example typical actions: "Refresh" in an email or social app, and "New contact" in the
People app.</p>
</ol>
<p>If you believe that more than four of your menu items can be justified as action items, then you
should carefully consider their relative level of importance and try to set no more than four as
action items (and do so using the {@code "ifRoom"} value to allow the system to put some back in the
overflow menu when space is limited on smaller screens). Even if space is available on a wide
screen, you should not create a long stream of action items that clutter the UI and appear like a
desktop toolbar, so keep the number of action items to a minimum.</p>
<p>Additionally, the following actions should never appear as action items: Settings, Help,
Feedback, or similar. Always keep them in the overflow menu.</p>
<p class="note"><strong>Note:</strong> Remember that not all devices provide a dedicated hardware
button for Search, so if it's an important feature in your app, it should always appear as an
action item (and usually as the first item, especially if you offer it with an <a
href="#ActionView">action view</a>).</p>
<h3 id="SplitBar">Using split action bar</h3>
<p>When your application is running on Android 4.0 (API level 14) and higher, there's an extra mode
available for the action bar called "split action bar." When you enable split action bar, a separate
bar appears at the bottom of the screen to display all action items when the activity is running on
a narrow screen (such as a portrait-oriented handset). Splitting the action bar to separate
the action items ensures that a reasonable amount of space is available to display all your action
items on a narrow screen, while leaving room for navigation and title elements at the top.</p>
<p>To enable split action bar, simply add {@code uiOptions="splitActionBarWhenNarrow"} to your
<a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> or
<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application>}</a>
manifest element.</p>
<p>Be aware that Android adjusts the action bar's appearance in a variety of ways, based on the
current screen size. Using split action bar is just one option that you can enable to allow the
action bar to further optimize the user experience for different screen sizes. In doing so, you
may also allow the action bar to collapse navigation tabs into the main action bar. That is, if you
use <a href="#Tabs">navigation tabs</a> in your action bar, once the action items are
separated on a narrow screen, the navigation tabs may be able to fit into the main action bar rather
than be separated into the "stacked action bar." Specifically, if you've disabled the action bar
icon and title (with {@link android.app.ActionBar#setDisplayShowHomeEnabled
setDisplayShowHomeEnabled(false)} and {@link android.app.ActionBar#setDisplayShowTitleEnabled
setDisplayShowTitleEnabled(false)}), then the navigation tabs collapse into the main action bar, as
shown by the second device in figure 3.</p>
<img src="{@docRoot}images/practices/actionbar-phone-splitaction.png" alt=""/>
<p class="img-caption"><strong>Figure 3.</strong> Mock-ups of split action bar with navigation tabs
on the left; with the app icon and title disabled on the right.</p>
<p class="note"><strong>Note:</strong> Although the {@link android.R.attr#uiOptions
android:uiOptions} attribute was added in Android 4.0 (API level 14), you can safely include it in
your application even if your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> is set to
a value lower than {@code "14"} to remain compatible with older versions of Android. When running on
older versions, the system simply ignores the XML attribute because it doesn't understand it. The
only condition to including it in your manifest is that you must compile your application against a
platform version that supports API level 14 or higher. Just be sure that you don't openly use other
APIs in your application code that aren't supported by the version declared by your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a>
attribute—only XML attributes are safely ignored by older platforms.</p>
<h2 id="Home">Using the App Icon for Navigation</h2>
<div class="sidebox-wrapper">
<div class="sidebox">
<h2>Using a logo instead of icon</h2>
<p>By default, the system uses your application icon in the action bar, as specified by the <a
href="{@docRoot}guide/topics/manifest/application-element.html#icon">{@code android:icon}</a>
attribute in the <a href="{@docRoot}guide/topics/manifest/application-element.html">{@code
<application>}</a> or <a
href="{@docRoot}guide/topics/manifest/activity-element.html">{@code
<activity>}</a> element. However, if you also specify the <a
href="{@docRoot}guide/topics/manifest/application-element.html#logo">{@code android:logo}</a>
attribute, then the action bar uses the logo image instead of the icon.</p>
<p>A logo should usually be wider than the icon, but should not include unnecessary text. You
should generally use a logo only when it represents your brand in a traditional format that users
recognize. A good example is the YouTube app's logo—the logo represents the expected user
brand, whereas the app's icon is a modified version that conforms to the square requirement.</p>
</div>
</div>
<p>By default, your application icon appears in the action bar on the left side. If you'd like,
you can enable the icon to behave as an action item. In response to user action on the icon, your
application should do one of two things:</p>
<ul>
<li>Go to the application "home" activity, or</li>
<li>Navigate "up" the application's structural hierarchy</li>
</ul>
<p>When the user touches the icon, the system calls your activity's {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method with the {@code
android.R.id.home} ID. In response, you should either start the home activity or
take the user one step up in your application's structural hierarchy.</p>
<p>If you respond to the application icon by returning to the home activity, you should include
the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag in the {@link
android.content.Intent}. With this flag, if the activity you're starting already exists in the
current task, then all activities on top of it are destroyed and it is brought to the front.
Adding this flag is often important because going "home" is an action that's equivalent to "going
back" and you should usually not create a new instance of the home activity. Otherwise, you
might end up with a long stack of activities in the current task with multiple instances of the
home activity.</p>
<p>For example, here's an implementation of {@link android.app.Activity#onOptionsItemSelected
onOptionsItemSelected()} that returns to the application's "home" activity:</p>
<pre>
@Override
public boolean onOptionsItemSelected(MenuItem item) {
switch (item.getItemId()) {
case android.R.id.home:
// app icon in action bar clicked; go home
Intent intent = new Intent(this, HomeActivity.class);
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
startActivity(intent);
return true;
default:
return super.onOptionsItemSelected(item);
}
}
</pre>
<p>In case the user can enter the current activity from another application, you might also want to
add the {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag. This flag ensures that, when the
user navigates either "home" or "up", the new activity is <strong>not</strong> added to the current
task, but instead started in a task that belongs to your application. For example, if the user
starts an activity in your application through an intent invoked by another application, then
selects the action bar icon to navigate home or up, the {@link
android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag starts the activity in a task that belongs to
your application (not the current task). The system either starts a new task with your new activity
as the root activity or, if an existing task exists in the background with an instance of that
activity, then that task is brought forward and the target activity receives {@link
android.app.Activity#onNewIntent onNewIntent()}. So if your activity accepts intents from other
applications (it declares any generic intent filters), you should usually add the {@link
android.content.Intent#FLAG_ACTIVITY_NEW_TASK} flag to the intent:</p>
<pre>
intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK);
</pre>
<p>For more information about these flags and other back stack behaviors, read the <a
href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>
developer guide.</p>
<p class="note"><strong>Note:</strong> If you're using the icon to navigate to the home
activity, beware that beginning with Android 4.0 (API level 14), you must explicitly enable the
icon as an action item by calling {@link android.app.ActionBar#setHomeButtonEnabled
setHomeButtonEnabled(true)} (in previous versions, the icon was enabled as an action item by
default).</p>
<h3 id="Up">Navigating up</h3>
<div class="figure" style="width:230px;margin-top:-1em">
<img src="{@docRoot}images/ui/actionbar-logo.png" alt="" />
<p class="img-caption"><strong>Figure 4.</strong> The Email app's standard icon
(left) and the "navigate up" icon (right). The system automatically adds the "up" indicator.</p>
</div>
<p>As a supplement to traditional "back" navigation—which takes the user to the previous
screen in the task history—you can enable the action bar icon to offer "up"
navigation, which should take the user one step up in your application's structural hierarchy. For
instance, if the current screen is somewhere deep in the hierarchy of the application, touching the
app icon should navigate upward one level, to the parent of the current screen.</p>
<p>For example, figure 5 illustrates how the BACK button behaves when the user navigates from one
application to an activity belonging to a different application (specifically, when composing an
email to a person selected from the People app).</p>
<img src="{@docRoot}images/ui/actionbar-navigate-back.png" alt="" />
<p class="img-caption"><strong>Figure 5.</strong> The BACK button behavior
after entering the Email app from the People (or Contacts) app.</p>
<p>However, if the user wants to stay within the email application after composing the email,
up navigation allows the user to navigate upward in the email application, rather than go back
to the previous activity. Figure 6 illustrates this scenario, in which the user again comes into
the email application, but presses the action bar icon to navigate up, rather than back.</p>
<img src="{@docRoot}images/ui/actionbar-navigate-up.png" alt="" />
<p class="img-caption"><strong>Figure 6.</strong> Example behavior for UP navigation after
entering the Email app from the People app.</p>
<div class="design-announce">
<p><strong>Navigation Design</strong></p>
<p>For more about how <em>Up</em> and <em>Back</em> navigation differ, read Android Design's <a
href="{@docRoot}design/patterns/navigation.html">Navigation</a> guide.</p>
</div>
<p>To enable the icon for up navigation (which displays the "up" indicator next to the icon), call
{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled(true)} on your
{@link android.app.ActionBar}:</p>
<pre>
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
ActionBar actionBar = getActionBar();
actionBar.setDisplayHomeAsUpEnabled(true);
...
}
</pre>
<p>When the user touches the icon, the system calls your activity's {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method with the {@code
android.R.id.home} ID, as shown in the above section about <a href="#Home">Using the App Icon
for Navigation</a>.</p>
<p>Remember to use the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag in the {@link
android.content.Intent}, so that you don't create a new instance of the parent activity if one
already exists. For instance, if you don't use the {@link
android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP} flag, then after navigating up, the BACK button will
actually take the user "forward", with respect to the application structure, which would be
strange.</p>
<p class="note"><strong>Note:</strong> If there are many paths that the user could have taken to
reach the current activity within your application, the up icon should navigate backward along the
path the user actually followed to get to the current activity.</p>
<h2 id="ActionView">Adding an Action View</h2>
<div class="figure" style="width:300px;margin-top:-1em">
<img src="/images/ui/actionbar-searchview.png" alt="" />
<p class="img-caption"><strong>Figure 7.</strong> An action bar with a collapsed action
view for Search (top), then expanded action view with the <code><a
href="/reference/android/widget/SearchView.html">SearchView</a></code> widget (bottom).</p>
</div>
<p>An action view is a widget that appears in the action bar as a substitute for an action item's
button. For example, if you have an item in the options menu for "Search," you can add an action
view that replaces the button with a {@link android.widget.SearchView} widget, as shown in figure
7.</p>
<p>To declare an action view for an item in your <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, use either the {@code
android:actionLayout} or {@code android:actionViewClass} attribute to specify either a layout
resource or widget class to use, respectively. For example:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/menu_search"
android:title="@string/menu_search"
android:icon="@drawable/ic_menu_search"
android:showAsAction="ifRoom|collapseActionView"
<b>android:actionViewClass="android.widget.SearchView"</b> />
</menu>
</pre>
<p>Notice that the {@code android:showAsAction} attribute also includes {@code
"collapseActionView"}. This is optional and declares that the action view should be collapsed into a
button. When the user selects the button, the action view expands. Otherwise, the action view is
visible by default and might consume valuable action bar space even when the user is not using it.
For more information, see the next section about <a href="#ActionViewCollapsing">Handling
collapsible action views</a>.</p>
<p>If you need to add some event hooks to your action view, you can do so during the {@link
android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} callback. You can acquire elements
in an action view by calling {@link android.view.Menu#findItem findItem()} with the ID of the menu
item, then call {@link android.view.MenuItem#getActionView}. For
example, the search widget from the above sample is acquired like this:</p>
<pre>
@Override
public boolean onCreateOptionsMenu(Menu menu) {
getMenuInflater().inflate(R.menu.options, menu);
SearchView searchView = (SearchView) menu.findItem(R.id.menu_search).getActionView();
// Configure the search info and add any event listeners
...
return super.onCreateOptionsMenu(menu);
}
</pre>
<p>For more information about using the search widget, see <a
href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</a>.</p>
<h3 id="ActionViewCollapsing">Handling collapsible action views</h3>
<div class="sidebox-wrapper">
<div class="sidebox">
<h3>Supporting Android 3.0 with an action view</h3>
<p>The {@code "collapseActionView"} option was added with Android 4.0 (API level 14). However, if
your application supports older versions, you should
still declare {@code "collapseActionView"} in order to better support smaller screens.
Devices running Android 4.0 and higher will show the action view collapsed, while older versions
work as designed otherwise.</p>
<p>Adding this value requires that you set your build target to Android 4.0 or higher in order to
compile. Older versions of Android ignore the {@code "collapseActionView"} value because they don't
understand it. Just be sure not to use other APIs in your source code that are not supported in the
version declared by your <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
minSdkVersion}</a>, unless you add the appropriate version check at runtime.</p>
</div>
</div>
<p>Action views allow you to provide fast access to rich actions without changing activities or
fragments, or replacing the action bar. However, it might not be appropriate to make an action view
visible by default. To preserve the action bar space (especially when running on smaller screens),
you can collapse your action view into an action item button. When the user selects the
button, the action view appears in the action bar. When collapsed, the system might place the item
into the overflow menu if you've defined {@code android:showAsAction} with {@code "ifRoom"}, but the
action view still appears in the action bar when the user selects the item. You can make your action
view collapsible by adding {@code "collapseActionView"} to the {@code android:showAsAction}
attribute, as shown in the XML above.</p>
<p>Because the system will expand the action view when the user selects the item, so you
<em>do not</em> need to respond to the item in the {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected} callback. The system still calls
{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} when the user selects it,
but the system will always expand the action view unless you return {@code true} (indicating
you've handled the event instead).</p>
<p>The system also collapses your action view when the user selects the "up" icon in the action
bar or presses the BACK button.</p>
<p>If necessary, you can expand or collapse the action view in your own code by calling {@link
android.view.MenuItem#expandActionView()} and {@link android.view.MenuItem#collapseActionView()} on
the {@link android.view.MenuItem}.</p>
<p class="note"><strong>Note:</strong> Although collapsing your action view is optional, we
recommend that you always collapse your action view if it includes {@link
android.widget.SearchView}. Also be aware that some devices provide a dedicated SEARCH button and
you should expand your search action view if the user presses the SEARCH button. Simply override
your activity's {@link android.app.Activity#onKeyUp onKeyUp()} callback method, listen for the
{@link android.view.KeyEvent#KEYCODE_SEARCH} event, then call {@link
android.view.MenuItem#expandActionView()}.</p>
<p>If you need to update your activity based on the visibility of your action view, you can receive
callbacks when it's expanded and collapsed by defining an {@link
android.view.MenuItem.OnActionExpandListener OnActionExpandListener} and registering it with {@link
android.view.MenuItem#setOnActionExpandListener setOnActionExpandListener()}. For example:</p>
<pre>
@Override
public boolean onCreateOptionsMenu(Menu menu) {
getMenuInflater().inflate(R.menu.options, menu);
MenuItem menuItem = menu.findItem(R.id.actionItem);
...
menuItem.setOnActionExpandListener(new OnActionExpandListener() {
@Override
public boolean onMenuItemActionCollapse(MenuItem item) {
// Do something when collapsed
return true; // Return true to collapse action view
}
@Override
public boolean onMenuItemActionExpand(MenuItem item) {
// Do something when expanded
return true; // Return true to expand action view
}
});
}
</pre>
<h2 id="ActionProvider">Adding an Action Provider</h2>
<div class="figure" style="width:200px">
<img src="{@docRoot}images/ui/actionbar-shareaction.png" alt="" />
<p class="img-caption"><strong>Figure 8.</strong> Screenshot from the Gallery app, with the
{@link android.widget.ShareActionProvider} submenu expanded to show share targets.</p>
</div>
<p>Similar to an <a href="#ActionView">action view</a>, an action provider (defined by the {@link
android.view.ActionProvider} class) replaces an action item with a customized layout, but it also
takes control of all the item's behaviors. When you declare an action provider for a menu
item in the action bar, it not only controls the appearance of the item in the action bar with a
custom layout, but also handles the default event for the menu item when it appears in the overflow
menu. It can also provide a submenu from either the action bar or the overflow menu.</p>
<p>For example, the {@link android.widget.ShareActionProvider} is an extension of {@link
android.view.ActionProvider} that facilitates a “share" action by showing a list of available share
targets from the action bar. Instead of using a
traditional action item that invokes the {@link android.content.Intent#ACTION_SEND} intent, you can
declare an instance of {@link android.widget.ShareActionProvider} to handle an action item. This
action provider presents an action view with a drop-down list of applications that handle
the {@link android.content.Intent#ACTION_SEND} intent, even when the menu item appears in the
overflow menu. Hence, when you use an action provider such as this one, you don't
have to handle user events on the menu item.</p>
<p>To declare an action provider for an action item, define the {@code android:actionProviderClass}
attribute for the appropriate the {@code <item>} element in your <a
href="{@docRoot}guide/topics/resources/menu-resource.html">menu resource</a>, using the
fully-qualified class name of the action provider. For example:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android">
<item android:id="@+id/menu_share"
android:title="@string/share"
android:showAsAction="ifRoom"
<strong>android:actionProviderClass="android.widget.ShareActionProvider"</strong> />
...
</menu>
</pre>
<p>In this example, the {@link android.widget.ShareActionProvider} is used as the action provider.
At this point, the action provider officially takes control of the menu item and handles both
its appearance and behavior in the action bar and its behavior in the overflow menu. You must
still provide a text title for the item to be used in the overflow menu.</p>
<p>Although the action provider can perform the default action for the menu item when it appears in
the overflow menu, your activity (or fragment) can override that behavior by
also handling the click event from the {@link android.app.Activity#onOptionsItemSelected
onOptionsItemSelected()} callback method. If you do not handle the event in that callback, then
the action provider receives the {@link android.view.ActionProvider#onPerformDefaultAction()}
callback to handle the event. However, if the action provider provides a submenu, then your
activity will not receive the {@link android.app.Activity#onOptionsItemSelected
onOptionsItemSelected()} callback, because the submenu is shown instead of invoking the default
menu item behavior when selected.</p>
<h3 id="ShareActionProvider">Using the ShareActionProvider</h3>
<p>If you want to provide a "share" action in your action bar by leveraging other applications
installed on the device (for example, to share a photo using a messaging or social app), then using
{@link android.widget.ShareActionProvider} is an effective way to do so, rather than adding an
action item that invokes the {@link android.content.Intent#ACTION_SEND} intent. When
you use {@link android.widget.ShareActionProvider} for an action item, it presents an action view
with a drop-down list of applications that handle the {@link android.content.Intent#ACTION_SEND}
intent (as shown in figure 8).</p>
<p>All the logic for creating the submenu, populating it with share targets, and handling click
events (including when the item appears in the overflow menu) is implemented by the {@link
android.widget.ShareActionProvider}—the only code you need to write is to declare the action
provider for the menu item and specify the share intent.</p>
<p>By default, the {@link android.widget.ShareActionProvider} retains a ranking for each
share target based on how often the user selects each one. The share targets used more frequently
appear at the top of the drop-down list and the target used most often appears directly in the
action bar as the default share target. By default, the ranking information is
saved in a private file with a name specified by {@link
android.widget.ShareActionProvider#DEFAULT_SHARE_HISTORY_FILE_NAME}. If you use the {@link
android.widget.ShareActionProvider} or an extension of it for only one type of action, then you
should continue to use this default history file and there's nothing you need to do. However, if you
use {@link android.widget.ShareActionProvider} or an extension of it for multiple actions with
semantically different meanings, then each {@link android.widget.ShareActionProvider} should specify
its own history file in order to maintain its own history. To specify a
different history file for the {@link android.widget.ShareActionProvider}, call {@link
android.widget.ShareActionProvider#setShareHistoryFileName setShareHistoryFileName()} and provide
an XML file name (for example, {@code "custom_share_history.xml"}).</p>
<p class="note"><strong>Note:</strong> Although the {@link android.widget.ShareActionProvider} ranks
share targets based on frequency of use, the behavior is extensible and extensions of {@link
android.widget.ShareActionProvider} can perform different behaviors and ranking based on the history
file (if appropriate).</p>
<p>To add {@link android.widget.ShareActionProvider}, simply define the {@code
android:actionProviderClass} attribute with {@code "android.widget.ShareActionProvider"}, as shown
in the XML example above. The only thing left to do is define
the {@link android.content.Intent} you want to use for sharing. To do so, you must call {@link
android.view.MenuItem#getActionProvider} to retrieve the {@link android.widget.ShareActionProvider}
that's associated with a {@link android.view.MenuItem}, then call {@link
android.widget.ShareActionProvider#setShareIntent setShareIntent()}.</p>
<p>If the format for the share intent depends on the selected item or other variables that change
during the activity lifecycle, you should save the {@link android.widget.ShareActionProvider} in a
member field and update it by calling {@link android.widget.ShareActionProvider#setShareIntent
setShareIntent()} as necessary. For example:</p>
<pre>
private ShareActionProvider mShareActionProvider;
...
@Override
public boolean onCreateOptionsMenu(Menu menu) {
mShareActionProvider = (ShareActionProvider) menu.findItem(R.id.menu_share).getActionProvider();
// If you use more than one ShareActionProvider, each for a different action,
// use the following line to specify a unique history file for each one.
// mShareActionProvider.setShareHistoryFileName("custom_share_history.xml");
// Set the default share intent
mShareActionProvider.setShareIntent(getDefaultShareIntent());
return true;
}
// When you need to update the share intent somewhere else in the app, call
// mShareActionProvider.{@link android.widget.ShareActionProvider#setShareIntent setShareIntent()}
</pre>
<p>The {@link android.widget.ShareActionProvider} now handles all user interaction with the item and
you <em>do not</em> need to handle click events from the {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} callback method.</p>
<p>For a sample using the share action provider, see
<a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarShareActionProviderActivity.html"
>ActionBarShareActionProviderActivity</a>.
<h3 id="CreatingActionProvider">Creating a custom action provider</h3>
<p>When you want to create an action view that has dynamic behaviors and a default action in the
overflow menu, extending {@link android.view.ActionProvider} to define those behaviors is a good
solution. Creating your own action provider offers you an organized and reusable component, rather
than handling the various action item transformations and behaviors in your fragment or activity
code. As shown in the previous section, Android provides one implementation of {@link
android.view.ActionProvider} for share actions: the {@link android.widget.ShareActionProvider}.</p>
<p>To create your own, simply extend the {@link android.view.ActionProvider} class and implement
its callback methods as appropriate. Most importantly, you should implement the following:</p>
<dl>
<dt>{@link android.view.ActionProvider#ActionProvider ActionProvider()}</dt>
<dd>This constructor passes you the application {@link android.content.Context}, which you
should save in a member field to use in the other callback methods.</dd>
<dt>{@link android.view.ActionProvider#onCreateActionView()}</dt>
<dd>This is where you define the action view for the item. Use the {@link
android.content.Context} acquired from the constructor to instantiate a {@link
android.view.LayoutInflater} and inflate your action view layout from an XML resource, then hook
up event listeners. For example:
<pre>
public View onCreateActionView() {
// Inflate the action view to be shown on the action bar.
LayoutInflater layoutInflater = LayoutInflater.from(mContext);
View view = layoutInflater.inflate(R.layout.action_provider, null);
ImageButton button = (ImageButton) view.findViewById(R.id.button);
button.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View v) {
// Do something...
}
});
return view;
}
</pre>
</dd>
<dt>{@link android.view.ActionProvider#onPerformDefaultAction()}</dt>
<dd>The system calls this when the menu item is selected from the overflow menu and the
action provider should perform a default action for the menu item.
<p>However, if your action provider provides a submenu, through the {@link
android.view.ActionProvider#onPrepareSubMenu onPrepareSubMenu()} callback, then the submenu
appears even when the menu item is in the overflow menu. Thus, {@link
android.view.ActionProvider#onPerformDefaultAction()} is never called when there is a
submenu.</p>
<p class="note"><strong>Note:</strong> An activity or a fragment that implements {@link
android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} can override the action
provider's default behavior by handling the item-selected event (and returning true), in which
case, the system does not call {@link android.view.ActionProvider#onPerformDefaultAction()}.</p>
</dd>
</dl>
<p>For an example extension of {@link android.view.ActionProvider}, see <a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/ActionBarSettingsActionProviderActivity.html"
>ActionBarSettingsActionProviderActivity</a>.</p>
<h2 id="Tabs">Adding Navigation Tabs</h2>
<div class="figure" style="width:450px">
<img src="{@docRoot}images/ui/actionbar.png" alt="" />
<p class="img-caption"><strong>Figure 9.</strong> Screenshot of action bar tabs from the <a
href="{@docRoot}resources/samples/HoneycombGallery/index.html">Honeycomb Gallery</a> app.</p>
</div>
<div class="figure" style="width:250px">
<img src="{@docRoot}images/ui/actionbar-stacked.png" alt="" />
<p class="img-caption"><strong>Figure 10.</strong> Screenshot of tabs in the stacked action
bar on a narrow screen.</p>
</div>
<p>When you want to provide navigation tabs in an activity, using the action bar's
tabs is a great option (instead of using {@link android.widget.TabWidget}), because the
system adapts the action bar tabs for different screen sizes—placing them in the main action
bar when the screen is sufficiently wide, or in a separate bar (known as the "stacked action bar")
when the screen is too narrow, as shown in figures 9 and 10.</p>
<p>To switch between fragments using the tabs, you must perform a fragment
transaction each time a tab is selected. If you're not familiar with how to change fragments
using {@link android.app.FragmentTransaction}, first read the <a
href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> developer guide.</p>
<p>To get started, your layout must include a {@link android.view.ViewGroup} in which you place each
{@link android.app.Fragment} associated with a tab. Be sure the {@link android.view.ViewGroup} has a
resource ID so you can reference it from your tab-swapping code. Alternatively, if the tab content
will fill the activity layout (excluding the action bar), then your activity doesn't need a layout
at all (you don't even need to call {@link android.app.Activity#setContentView
setContentView()}). Instead, you can place each fragment in the default root {@link
android.view.ViewGroup}, which you can refer to with the {@code android.R.id.content} ID (you can
see this ID used in the sample code below, during fragment transactions).</p>
<p>Once you determine where the fragments appear in the layout, the basic procedure to add tabs
is:</p>
<ol>
<li>Implement the {@link android.app.ActionBar.TabListener} interface. Callbacks in this
interface respond to user events on the tabs so you can swap fragments.</li>
<li>For each tab you want to add, instantiate an {@link android.app.ActionBar.Tab} and set the
{@link android.app.ActionBar.TabListener} by calling {@link android.app.ActionBar.Tab#setTabListener
setTabListener()}. Also set the tab's title and/or icon with {@link
android.app.ActionBar.Tab#setText setText()} and/or {@link android.app.ActionBar.Tab#setIcon
setIcon()}.</li>
<li>Add each tab to the action bar by calling {@link android.app.ActionBar#addTab addTab()}.</li>
</ol>
<p>When looking at the {@link android.app.ActionBar.TabListener} interface, notice that the
callback methods provide only the {@link android.app.ActionBar.Tab} that was selected and a {@link
android.app.FragmentTransaction} for you to perform fragment transactions—it doesn't say
anything about what fragment you should swap in or out. Thus, you must define your own association
between each {@link android.app.ActionBar.Tab} and the appropriate {@link android.app.Fragment} that
it represents (in order to perform the appropriate fragment transaction). There are several ways you
can define the association, depending on your design. In the example below, the {@link
android.app.ActionBar.TabListener} implementation provides a constructor such that each new tab uses
its own instance of the listener. Each instance of the listener defines several fields that are
necessary to later perform a transaction on the appropriate fragment.</p>
<p>For example, here's how you might implement the {@link android.app.ActionBar.TabListener}
such that each tab uses its own instance of the listener:</p>
<pre>
public static class TabListener<T extends Fragment> implements ActionBar.TabListener {
private Fragment mFragment;
private final Activity mActivity;
private final String mTag;
private final Class<T> mClass;
/** Constructor used each time a new tab is created.
* @param activity The host Activity, used to instantiate the fragment
* @param tag The identifier tag for the fragment
* @param clz The fragment's Class, used to instantiate the fragment
*/
public TabListener(Activity activity, String tag, Class<T> clz) {
mActivity = activity;
mTag = tag;
mClass = clz;
}
/* The following are each of the {@link android.app.ActionBar.TabListener} callbacks */
public void onTabSelected(Tab tab, FragmentTransaction ft) {
// Check if the fragment is already initialized
if (mFragment == null) {
// If not, instantiate and add it to the activity
mFragment = Fragment.instantiate(mActivity, mClass.getName());
ft.add(android.R.id.content, mFragment, mTag);
} else {
// If it exists, simply attach it in order to show it
ft.attach(mFragment);
}
}
public void onTabUnselected(Tab tab, FragmentTransaction ft) {
if (mFragment != null) {
// Detach the fragment, because another one is being attached
ft.detach(mFragment);
}
}
public void onTabReselected(Tab tab, FragmentTransaction ft) {
// User selected the already selected tab. Usually do nothing.
}
}
</pre>
<p class="caution"><strong>Caution:</strong> You <strong>must not</strong> call {@link
android.app.FragmentTransaction#commit} for the fragment transaction in each of these
callbacks—the system calls it for you and it may throw an exception if you call it yourself.
You also <strong>cannot</strong> add these fragment transactions to the back stack.</p>
<p>In this example, the listener simply attaches ({@link android.app.FragmentTransaction#attach
attach()}) a fragment to the activity layout—or if not instantiated, creates the fragment and
adds ({@link android.app.FragmentTransaction#add add()}) it to the layout (as a child of the {@code
android.R.id.content} view group)—when the respective tab is selected, and detaches ({@link
android.app.FragmentTransaction#detach detach()}) it when the tab is unselected.</p>
<p>The {@link android.app.ActionBar.TabListener} implementation is the bulk of the work. All that
remains is to create each {@link android.app.ActionBar.Tab} and add it to the {@link
android.app.ActionBar}. Additionally, you must call {@link
android.app.ActionBar#setNavigationMode(int) setNavigationMode(NAVIGATION_MODE_TABS)} to make the
tabs visible. You might also want to disable the activity title by calling {@link
android.app.ActionBar#setDisplayShowTitleEnabled setDisplayShowTitleEnabled(false)} if the tab
titles actually indicate the current view.</p>
<p>For example, the following code adds two tabs using the listener defined above:</p>
<pre>
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
// Notice that setContentView() is not used, because we use the root
// android.R.id.content as the container for each fragment
// setup action bar for tabs
ActionBar actionBar = getActionBar();
actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS);
actionBar.setDisplayShowTitleEnabled(false);
Tab tab = actionBar.newTab()
.setText(R.string.artist)
.setTabListener(new TabListener<ArtistFragment>(
this, "artist", ArtistFragment.class));
actionBar.addTab(tab);
tab = actionBar.newTab()
.setText(R.string.album)
.setTabListener(new TabListener<AlbumFragment>(
this, "album", AlbumFragment.class));
actionBar.addTab(tab);
}
</pre>
<p class="note"><strong>Note:</strong> The above implementation for {@link
android.app.ActionBar.TabListener} is one of several possible techniques. You can see more of
this style in the <a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/FragmentTabs.html"
>API Demos</a> app.</p>
<p>If your activity stops, you should retain the currently selected tab with the <a
href="{@docRoot}guide/topics/fundamentals/activities.html#SavingActivityState">saved instance
state</a> so you can open the appropriate tab when the user returns. When it's time to save the
state, you can query the currently selected tab with {@link
android.app.ActionBar#getSelectedNavigationIndex()}. This returns the index position of the selected
tab.</p>
<p class="caution"><strong>Caution:</strong> It's important that you save the state of each fragment
as necessary, so that when users switch fragments with the tabs and then return to a previous
fragment, it looks the way it did when they left. For information about saving the state of your
fragment, see the <a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a>
developer guide.</p>
<p class="note"><strong>Note:</strong> In some cases, the Android system will show your action
bar tabs as a drop-down list in order to ensure the best fit in the action bar.</p>
<h2 id="Dropdown">Adding Drop-down Navigation</h2>
<p>As another mode of navigation (or filtering) within your activity, the action bar offers a
built in drop-down list. For example, the drop-down list can offer different modes by which content
in the activity is sorted.</p>
<!--
<div class="figure" style="width:135px">
<img src="{@docRoot}images/ui/actionbar-dropdown.png" alt="" />
<p class="img-caption"><strong>Figure 5.</strong> Screenshot of a drop-down navigation list in the
action bar.</p>
</div>
-->
<p>The basic procedure to enable drop-down navigation is:</p>
<ol>
<li>Create a {@link android.widget.SpinnerAdapter} that provides the
list of selectable items for the drop-down and the layout to use when drawing each item in the
list.</li>
<li>Implement {@link android.app.ActionBar.OnNavigationListener} to define the behavior that
occurs when the user selects an item from the list.</li>
<li>Enable navigation mode for the action bar with {@link
android.app.ActionBar#setNavigationMode setNavigationMode()}. For example:
<pre>
ActionBar actionBar = getActionBar();
actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST);
</pre>
<p class="note"><strong>Note:</strong> You should perform this during your activity's {@link
android.app.Activity#onCreate
onCreate()} method.</p>
</li>
<li>Set the callback for the drop-down list with {@link
android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}. For example:
<pre>
actionBar.setListNavigationCallbacks(mSpinnerAdapter, mNavigationCallback);
</pre>
<p>This method takes your {@link android.widget.SpinnerAdapter} and {@link
android.app.ActionBar.OnNavigationListener}.</p>
</li>
</ol>
<p>That's the basic setup. However, implementing the {@link android.widget.SpinnerAdapter} and
{@link android.app.ActionBar.OnNavigationListener} is where most of the work is done. There are many
ways you can implement these to define the functionality for your drop-down navigation and
implementing various types of {@link android.widget.SpinnerAdapter} is beyond the scope of this
document (you should refer to the {@link android.widget.SpinnerAdapter} class reference for more
information). However, below is a simple example for a {@link android.widget.SpinnerAdapter} and
{@link android.app.ActionBar.OnNavigationListener} to get you started (click the title to
reveal the sample).</p>
<div class="toggle-content closed">
<h3 id="Spinner"><a href="#" onclick="return toggleContent(this)">
<img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" />
Example SpinnerAdapter and OnNavigationListener
</a></h3>
<div class="toggle-content-toggleme">
<p>{@link android.widget.SpinnerAdapter} is an adapter that provides data for a spinner widget,
such as the drop-down list in the action bar. {@link android.widget.SpinnerAdapter} is an interface
that you can implement, but Android includes some useful implementations that you can extend, such
as {@link android.widget.ArrayAdapter} and {@link
android.widget.SimpleCursorAdapter}. For example, here's an easy way to create a {@link
android.widget.SpinnerAdapter} by using {@link android.widget.ArrayAdapter} implementation, which
uses a string array as the data source:</p>
<pre>
SpinnerAdapter mSpinnerAdapter = ArrayAdapter.createFromResource(this, R.array.action_list,
android.R.layout.simple_spinner_dropdown_item);
</pre>
<p>The {@link android.widget.ArrayAdapter#createFromResource createFromResource()} method takes
three parameters: the application {@link android.content.Context}, the resource ID for the string
array, and the layout to use for each list item.</p>
<p>A <a href="{@docRoot}guide/topics/resources/string-resource.html#StringArray">string array</a>
defined in a resource looks like this:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="action_list">
<item>Mercury</item>
<item>Venus</item>
<item>Earth</item>
</string-array>
</pre>
</pre>
<p>The {@link android.widget.ArrayAdapter} returned by {@link
android.widget.ArrayAdapter#createFromResource createFromResource()} is complete and ready for you
to pass it to {@link android.app.ActionBar#setListNavigationCallbacks setListNavigationCallbacks()}
(in step 4 from above). Before you do, though, you need to create the {@link
android.app.ActionBar.OnNavigationListener OnNavigationListener}.</p>
<p>Your implementation of {@link android.app.ActionBar.OnNavigationListener} is where you handle
fragment changes or other modifications to your activity when the user selects an item from the
drop-down list. There's only one callback method to implement in the listener: {@link
android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}.</p>
<p>The {@link
android.app.ActionBar.OnNavigationListener#onNavigationItemSelected onNavigationItemSelected()}
method receives the position of the item in the list and a unique item ID provided by the {@link
android.widget.SpinnerAdapter}.</p>
<p>Here's an example that instantiates an anonymous implementation of {@link
android.app.ActionBar.OnNavigationListener OnNavigationListener}, which inserts a {@link
android.app.Fragment} into the
layout container identified by {@code R.id.fragment_container}:</p>
<pre>
mOnNavigationListener = new OnNavigationListener() {
// Get the same strings provided for the drop-down's ArrayAdapter
String[] strings = getResources().getStringArray(R.array.action_list);
@Override
public boolean onNavigationItemSelected(int position, long itemId) {
// Create new fragment from our own Fragment class
ListContentFragment newFragment = new ListContentFragment();
FragmentTransaction ft = openFragmentTransaction();
// Replace whatever is in the fragment container with this fragment
// and give the fragment a tag name equal to the string at the position selected
ft.replace(R.id.fragment_container, newFragment, strings[position]);
// Apply changes
ft.commit();
return true;
}
};
</pre>
<p>This instance of {@link android.app.ActionBar.OnNavigationListener OnNavigationListener} is
complete and you can now call {@link android.app.ActionBar#setListNavigationCallbacks
setListNavigationCallbacks()} (in step 4), passing the {@link android.widget.ArrayAdapter} and this
{@link android.app.ActionBar.OnNavigationListener OnNavigationListener}.</p>
<p>In this example, when the user selects an item from the drop-down list, a fragment is added to
the layout (replacing the current fragment in the {@code R.id.fragment_container} view). The
fragment added is given a tag that uniquely identifies it, which is the same string used to
identify the fragment in the drop-down list.</p>
<p>Here's a look at the {@code ListContentFragment} class that defines each fragment in this
example:</p>
<pre>
public class ListContentFragment extends Fragment {
private String mText;
@Override
public void onAttach(Activity activity) {
// This is the first callback received; here we can set the text for
// the fragment as defined by the tag specified during the fragment transaction
super.onAttach(activity);
mText = getTag();
}
@Override
public View onCreateView(LayoutInflater inflater, ViewGroup container,
Bundle savedInstanceState) {
// This is called to define the layout for the fragment;
// we just create a TextView and set its text to be the fragment tag
TextView text = new TextView(getActivity());
text.setText(mText);
return text;
}
}
</pre>
</div><!-- end toggle-content-toggleme -->
</div><!-- end toggle-content -->
<h2 id="Style">Styling the Action Bar</h2>
<p>If you've implemented a custom design for the widgets in your application, you might
also want to redesign some of the action bar to match your app design. To do so, you need to use
Android's <a
href="{@docRoot}guide/topics/ui/themes.html">style and theme</a> framework to restyle the action
bar using special style properties.</p>
<p class="note"><strong>Note:</strong> In order for background images to change appearance
depending on the current button state (selected, pressed, unselected), the drawable resource you use
must be a <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">state
list drawable</a>.</p>
<p class="caution"><strong>Caution:</strong> For all background drawables you provide, be sure to use <a
href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch drawables</a> to allow
stretching. The Nine-Patch image should be <em>smaller</em> than 40px tall and 30px wide (for the mdpi asset).</p>
<h3 id="GeneralStyles">General appearance</h3>
<dl>
<dt>{@link android.R.attr#windowActionBarOverlay
android:windowActionBarOverlay}</dt>
<dd>Declares whether the action bar should overlay the activity layout rather than offset the
activity's layout position (for example, the Gallery app uses overlay mode). This is
{@code false} by default.
<p>Normally, the action bar requires its own space on the screen and your activity layout fills in
what's left over. When the action bar is in overlay mode, your activity layout uses all the
available space and the system draws the action bar on top. Overlay mode can be useful if you want
your content to keep a fixed size and position when the action bar is hidden and shown. You might
also like to use it purely as a visual effect, because you can use a semi-transparent background
for the action bar so the user can still see some of your activity layout behind the action
bar.</p>
<p class="note"><strong>Note:</strong> The {@link android.R.style#Theme_Holo Holo} theme families
draw the action bar with a semi-transparent background by default. However, you can modify it with
your own styles and the {@link android.R.style#Theme_DeviceDefault DeviceDefault} theme on
different devices might use an opaque background by default.</p>
<p>When overlay mode is enabled, your activity layout has no awareness of the action bar laying on
top of it. So, you must be careful not to place any important information or UI components in the
area overlayed by the action bar. If appropriate, you can refer to the platform's value for {@link
android.R.attr#actionBarSize} to determine the height of the action bar, by referencing it
in your XML layout. For example:</p>
<pre>
<SomeView
...
android:layout_marginTop="?android:attr/actionBarSize" />
</pre>
<p>You can also retrieve the action bar height at runtime with {@link
android.app.ActionBar#getHeight()}. This reflects the height of the action bar at the time it's
called, which might not include the stacked action bar (due to navigation tabs) if called during early
activity lifecycle methods. To see how you can determine the total height at runtime, including the
stacked action bar, see the <a
href="{@docRoot}resources/samples/HoneycombGallery/src/com/example/android/hcgallery/TitlesFragment.html"
>{@code TitlesFragment}</a> class in the <a
href="{@docRoot}resources/samples/HoneycombGallery/index.html"
>Honeycomb Gallery</a> sample app.</p>
</dd>
</dl>
<h3 id="ActionItemStyles">Action items</h3>
<dl>
<dt>{@link android.R.attr#actionButtonStyle
android:actionButtonStyle}</dt>
<dd>Defines a style resource for the action item buttons.</dd>
<dt>{@link android.R.attr#actionBarItemBackground
android:actionBarItemBackground}</dt>
<dd>Defines a drawable resource for each action item's background. (Added in API level 14.)</dd>
<dt>{@link android.R.attr#itemBackground
android:itemBackground}</dt>
<dd>Defines a drawable resource for each overflow menu item's background.</dd>
<dt>{@link android.R.attr#actionBarDivider
android:actionBarDivider}</dt>
<dd>Defines a drawable resource for the divider between action items. (Added in API level
14.)</dd>
<dt>{@link android.R.attr#actionMenuTextColor
android:actionMenuTextColor}</dt>
<dd>Defines a color for text that appears in an action item.</dd>
<dt>{@link android.R.attr#actionMenuTextAppearance
android:actionMenuTextAppearance}</dt>
<dd>Defines a style resource for text that appears in an action item.</dd>
<dt>{@link android.R.attr#actionBarWidgetTheme
android:actionBarWidgetTheme}</dt>
<dd>Defines a theme resource for widgets that are inflated into the action bar as <a
href="#ActionView">action views</a>. (Added in API level 14.)</dd>
</dl>
<h3 id="NavigationStyles">Navigation tabs</h3>
<dl>
<dt>{@link android.R.attr#actionBarTabStyle
android:actionBarTabStyle}</dt>
<dd>Defines a style resource for tabs in the action bar.</dd>
<dt>{@link android.R.attr#actionBarTabBarStyle
android:actionBarTabBarStyle}</dt>
<dd>Defines a style resource for the thin bar that appears below the navigation tabs.</dd>
<dt>{@link android.R.attr#actionBarTabTextStyle
android:actionBarTabTextStyle}</dt>
<dd>Defines a style resource for text in the navigation tabs.</dd>
</dl>
<h3 id="DropDownStyles">Drop-down lists</h3>
<dl>
<dt>{@link android.R.attr#actionDropDownStyle
android:actionDropDownStyle}</dt>
<dd>Defines a style for the drop-down navigation (such as the background and text styles).</dd>
</dl>
<p>For example, here's a file that defines a few custom styles for the action bar:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- the theme applied to the application or activity -->
<style name="CustomActivityTheme" parent="@android:style/Theme.Holo">
<item name="android:actionBarTabTextStyle">@style/CustomTabTextStyle</item>
<item name="android:actionBarDivider">@drawable/ab_divider</item>
<item name="android:actionBarItemBackground">@drawable/ab_item_background</item>
</style>
<!-- style for the action bar tab text -->
<style name="CustomTabTextStyle">
<item name="android:textColor">#2456c2</item>
</style>
</resources>
</pre>
<p class="note"><strong>Note:</strong> Be certain that your theme declares a parent theme in the
{@code <style>} tag, from which it inherits all styles not explicitly declared by your theme.
When modifying the action bar, using a parent theme is important so that you can simply override the
action bar styles you want to change without re-implementing the styles you want to leave alone
(such as text appearance or padding in action items).</p>
<p>You can apply your custom theme to the entire application or to individual activities in your
manifest file like this:</p>
<pre>
<application android:theme="@style/CustomActivityTheme"
... />
</pre>
<p>For more information about using style and theme resources in your application, read <a
href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a>.</p>
<h3 id="AdvancedStyles">Advanced styling</h3>
<p>If you need more advanced styling for the action bar than is available with the
properties above, you can include {@link android.R.attr#actionBarStyle android:actionBarStyle} and
{@link android.R.attr#actionBarSplitStyle android:actionBarSplitStyle} in your activity's theme.
Each of these specifies another style that can define various properties for the action bar,
including different backgrounds with {@link android.R.attr#background android:background}, {@link
android.R.attr#backgroundSplit android:backgroundSplit}, and {@link android.R.attr#backgroundStacked
android:backgroundStacked}. If you override these action bar styles, be sure that you define a
parent action bar style such as {@link android.R.style#Widget_Holo_ActionBar
Widget.Holo.ActionBar}.</p>
<p>For example, if you want to change the action bar's background, you could use the following
styles:</p>
<pre>
<?xml version="1.0" encoding="utf-8"?>
<resources>
<!-- the theme applied to the application or activity -->
<style name="CustomActivityTheme" parent="@android:style/Theme.Holo">
<item name="android:actionBarTabTextStyle">@style/customTabTextStyle</item>
<!-- other activity and action bar styles here -->
</style>
<!-- style for the action bar, simply to change the background -->
<style parent="@android:style/Widget.Holo.ActionBar">
<item name="android:background">@drawable/ab_background</item>
<item name="android:backgroundSplit">@drawable/ab_background</item>
</style>
</resources>
</pre>
|