1page.title=Adding an Up Action
2page.tags="appbar","actionbar", "up"
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>
15        <a href="#declare-parent">Declare a Parent Activity</a>
16      </li>
17
18      <li>
19        <a href="#enable-up">Enable the Up Button</a>
20      </li>
21    </ol>
22
23    <h2>See Also</h2>
24    <ul>
25      <li><a href="{@docRoot}training/implementing-navigation/ancestral.html">
26          Providing Up Navigation</a></li>
27    </ul>
28
29
30  </div>
31</div>
32
33<p>
34  Your app should make it easy for users to find their way back to the app's
35  main screen. One simple way to do this is to provide an <em>Up</em>
36  button on the app bar for all activities except the main one. When the user
37  selects the <em>Up</em> button, the app navigates to the parent
38  activity.
39</p>
40
41<p>
42  This lesson shows you how to add an <em>Up</em> button to an activity by
43  declaring the activity's parent in the manifest, and enabling the app bar's
44  <em>Up</em> button.
45</p>
46
47<h2 id="declare-parent">Declare a Parent Activity</h2>
48
49<p>
50  To support the up functionality in an activity, you need to declare the
51  activity's parent. You can do this in the app manifest, by setting an
52  <code>android:parentActivityName</code> attribute.
53</p>
54
55<p>
56  The <code>android:parentActivityName</code> attribute
57  was introduced in Android 4.1 (API level 16). To support devices with older
58  versions of Android, define a <a href=
59  "{@docRoot}guide/topics/manifest/meta-data-element.html"><code>&lt;meta-data&gt;</code></a>
60  name-value pair, where the name is
61  <code>"android.support.PARENT_ACTIVITY"</code> and the value is the name of
62  the parent activity.
63</p>
64
65<p>
66  For example, suppose your app has a main activity named
67  <code>MainActivity</code> and a single child activity. The following manifest
68  code declares both activities, and specifies the parent/child relationship:
69</p>
70<pre>
71&lt;application ... &gt;
72    ...
73
74    &lt;!-- The main/home activity (it has no parent activity) --&gt;
75
76    &lt;activity
77        android:name="com.example.myfirstapp.MainActivity" ...&gt;
78        ...
79    &lt;/activity&gt;
80
81    &lt;!-- A child of the main activity --&gt;
82    &lt;activity
83        android:name="com.example.myfirstapp.MyChildActivity"
84        android:label="@string/title_activity_child"
85        <strong>android:parentActivityName="com.example.myfirstapp.MainActivity"</strong> &gt;
86
87        &lt;!-- Parent activity meta-data to support 4.0 and lower --&gt;
88        &lt;meta-data
89            <strong>android:name="android.support.PARENT_ACTIVITY"
90            android:value="com.example.myfirstapp.MainActivity" /&gt;</strong>
91    &lt;/activity&gt;
92&lt;/application&gt;
93</pre>
94
95<h2 id="enable-up">Enable the Up Button</h2>
96
97<p>
98  To enable the <em>Up</em> button for an activity that has a parent
99  activity, call the app bar's {@link
100  android.support.v7.app.ActionBar#setDisplayHomeAsUpEnabled
101  setDisplayHomeAsUpEnabled()} method. Typically, you would do this when the
102  activity is created. For example, the following {@link
103  android.app.Activity#onCreate onCreate()} method sets a {@link
104  android.support.v7.widget.Toolbar} as the app bar for
105  <code>MyChildActivity</code>, then enables that app bar's <em>Up</em> button:
106</p>
107
108<pre>
109&#64;Override
110protected void onCreate(Bundle savedInstanceState) {
111    super.onCreate(savedInstanceState);
112    setContentView(R.layout.activity_my_child);
113
114    // my_child_toolbar is defined in the layout file
115    Toolbar myChildToolbar =
116        (Toolbar) findViewById(R.id.my_child_toolbar);
117    setSupportActionBar(myChildToolbar);
118
119    // Get a support ActionBar corresponding to this toolbar
120    ActionBar ab = getSupportActionBar();
121
122    // Enable the Up button
123    <strong>ab.setDisplayHomeAsUpEnabled(true);</strong>
124}
125</pre>
126
127<p>
128  You do <em>not</em> need to catch the up action in the activity's {@link
129  android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} method.
130  Instead, that method should call its superclass, as shown in <a href=
131  "actions.html#handle-actions">Respond to Actions</a>. The superclass method
132  responds to the <em>Up</em> selection by navigating to the parent
133  activity, as specified in the app manifest.
134</p>
135