Home | History | Annotate | Download | only in appbar 
      1 page.title=Adding an Up Action
      2 page.tags="appbar","actionbar", "up"
      3 helpoutsWidget=true
      4 trainingnavtop=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
    110 protected 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