1page.title=Setting Up the App Bar
2page.tags="appbar","actionbar", "toolbar"
3helpoutsWidget=true
4trainingnavtop=true
5
6@jd:body
7
8<div id="tb-wrapper">
9  <div id="tb">
10
11    <h2>This lesson teaches you to</h2>
12
13    <ol>
14      <li><a href="#add-toolbar">Add a Toolbar to an Activity</a></li>
15      <li><a href="#utility">Use App Bar Utility Methods</a></li>
16    </ol>
17
18    <h2>You should also read</h2>
19    <ul>
20      <li><a href="{@docRoot}tools/support-library/setup.html"
21    >Setting Up the Support Library</a></li>
22    </ul>
23  </div>
24</div>
25
26
27<p>
28  In its most basic form, the action bar displays the title for the activity on
29  one side and an <em>overflow menu</em> on the other. Even in this simple
30  form, the app bar provides useful information to the users, and helps to give
31  Android apps a consistent look and feel.
32</p>
33
34<img src="{@docRoot}images/training/appbar/appbar_basic_2x.png"
35    srcset="{@docRoot}images/training/appbar/appbar_basic.png 1x,
36        {@docRoot}images/training/appbar/appbar_basic_2x.png 2x"
37    width="400" alt="" />
38<p class="img-caption"><strong>Figure 1.</strong> An app bar with the app
39title and overflow menu.</a>
40
41<p>
42  Beginning with Android 3.0 (API level 11), all
43  activities that use the default theme have an {@link android.app.ActionBar}
44  as an app bar. However, app bar features have gradually been added to the
45  native {@link android.app.ActionBar} over various Android releases. As a
46  result, the native {@link android.app.ActionBar} behaves differently
47  depending on what version of the Android system a device may be using. By
48  contrast, the most recent features are added to the support library's version
49  of {@link android.support.v7.widget.Toolbar}, and they are available on any
50  device that can use the support library.
51</p>
52
53<p>
54  For this reason, you should use the support library's {@link
55  android.support.v7.widget.Toolbar} class to implement your activities' app
56  bars. Using the support library's toolbar helps ensure that your app will
57  have consistent behavior across the widest range of devices. For example, the
58  {@link android.support.v7.widget.Toolbar} widget provides a <a href=
59  "{@docRoot}design/material/index.html">material design</a> experience on
60  devices running Android 2.1 (API level 7) or later, but the native action
61  bar doesn't support material design unless the device is running Android 5.0
62  (API level 21) or later.
63</p>
64
65<h2 id="add-toolbar">Add a Toolbar to an Activity</h2>
66
67These steps describe how to set up a {@link android.support.v7.widget.Toolbar}
68as your activity's app bar:
69
70<ol>
71  <li>Add the
72  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
73  appcompat</a> support library to your project, as described in <a href=
74  "{@docRoot}tools/support-library/setup.html">Support Library Setup</a>.
75  </li>
76
77  <li>Make sure the activity extends {@link
78  android.support.v7.app.AppCompatActivity}:
79
80    <pre>
81public class MyActivity extends AppCompatActivity {
82  // ...
83}
84</pre>
85    <p class="note">
86      <strong>Note:</strong> Make this change for every activity in your app
87      that uses a {@link android.support.v7.widget.Toolbar} as an app bar.
88    </p>
89  </li>
90
91  <li>In the app manifest, set the <a href=
92  "{@docRoot}guide/topics/manifest/application-element.html"><code>&lt;application&gt;</code></a>
93  element to use one of appcompat's {@link
94  android.support.v7.appcompat.R.style#Theme_AppCompat_NoActionBar NoActionBar}
95  themes. Using one of these themes prevents the app from using the native
96  {@link android.app.ActionBar} class to provide the app bar. For example:
97
98    <pre>
99&lt;application
100    android:theme="&#64;style/Theme.AppCompat.Light.NoActionBar"
101    /&gt;
102</pre>
103  </li>
104
105  <li>Add a {@link android.support.v7.widget.Toolbar} to the activity's layout.
106  For example, the following layout code adds a {@link
107  android.support.v7.widget.Toolbar} and gives it the appearance of floating
108  above the activity:
109
110    <pre>
111&lt;android.support.v7.widget.Toolbar
112   android:id="&#64;+id/my_toolbar"
113   android:layout_width="match_parent"
114   android:layout_height="?attr/actionBarSize"
115   android:background="?attr/colorPrimary"
116   android:elevation="4dp"
117   android:theme="&#64;style/ThemeOverlay.AppCompat.ActionBar"
118   app:popupTheme="&#64;style/ThemeOverlay.AppCompat.Light"/&gt;
119</pre>
120    <p>
121      The <a href=
122      "https://www.google.com/design/spec/what-is-material/elevation-shadows.html#elevation-shadows-shadows">
123      Material Design specification</a> recommends that app bars have an
124      elevation of 4 dp.
125    </p>
126
127    <p>
128      Position the toolbar at the top of the activity's
129      <a href="{@docRoot}guide/topics/ui/declaring-layout.html">layout</a>,
130      since you are using it as an app bar.
131    </p>
132  </li>
133
134  <li>In the activity's {@link android.app.Activity#onCreate onCreate()}
135  method, call the activity's {@link
136  android.support.v7.app.AppCompatActivity#setSupportActionBar
137  setSupportActionBar()} method, and pass the activity's toolbar. This method
138  sets the toolbar as the app bar for the activity. For example:
139
140    <pre>
141&#64;Override
142protected void onCreate(Bundle savedInstanceState) {
143    super.onCreate(savedInstanceState);
144    setContentView(R.layout.activity_my);
145    <strong>Toolbar myToolbar = (Toolbar) findViewById(R.id.my_toolbar);
146    setSupportActionBar(myToolbar);</strong>
147    }
148</pre>
149  </li>
150</ol>
151
152<p>
153  Your app now has a basic action bar. By default, the action bar contains just
154  the name of the app and an overflow menu. The options menu initially contains
155  just the <strong>Settings</strong> item. You can add more actions to the
156  action bar and the overflow menu, as described in <a href=
157  "actions.html">Adding and Handling Actions</a>.
158</p>
159
160<h2 id="utility">Use App Bar Utility Methods</h2>
161
162<p>
163  Once you set the toolbar as an activity's app bar, you have access to the
164  various utility methods provided by the
165  <a href="{@docRoot}tools/support-library/features.html#v7-appcompat">v7
166  appcompat</a> support library's {@link
167  android.support.v7.app.ActionBar} class. This approach lets you do a number of useful
168  things, like hide and show the app bar.
169</p>
170
171<p>
172  To use the {@link android.support.v7.app.ActionBar} utility methods, call the
173  activity's {@link
174  android.support.v7.app.AppCompatActivity#getSupportActionBar
175  getSupportActionBar()} method. This method returns a reference to an
176  appcompat {@link android.support.v7.app.ActionBar} object.
177  Once you have that reference, you can call any of the {@link
178  android.support.v7.app.ActionBar} methods to adjust the app bar. For example,
179  to hide the app bar, call {@link android.support.v7.app.ActionBar#hide
180  ActionBar.hide()}.
181</p>
182