1page.title=Implementing Ancestral Navigation 2parent.title=Implementing Effective Navigation 3parent.link=index.html 4 5trainingnavtop=true 6previous.title=Implementing Lateral Navigation 7previous.link=lateral.html 8next.title=Implementing Temporal Navigation 9next.link=temporal.html 10 11@jd:body 12 13<div id="tb-wrapper"> 14<div id="tb"> 15 16<h2>This lesson teaches you to:</h2> 17<ol> 18 <li><a href="#up">Implement <em>Up</em> Navigation</a></li> 19 <li><a href="#app-home">Properly Handle the Application Home Screen</a></li> 20</ol> 21 22<h2>You should also read</h2> 23<ul> 24 <li><a href="{@docRoot}training/design-navigation/ancestral-temporal.html">Providing Ancestral and Temporal Navigation</a></li> 25 <li><a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a></li> 26 <li><a href="{@docRoot}design/patterns/navigation.html">Android Design: Navigation</a></li> 27</ul> 28 29<h2>Try it out</h2> 30 31<div class="download-box"> 32<a href="http://developer.android.com/shareables/training/EffectiveNavigation.zip" 33 class="button">Download the sample app</a> 34<p class="filename">EffectiveNavigation.zip</p> 35</div> 36 37</div> 38</div> 39 40 41<p><em>Ancestral navigation</em> is up the application's information hierarchy, where the top of the hierarchy (or root) is the application's home screen. This navigation concept is described in <a href="{@docRoot}training/design-navigation/ancestral-temporal.html">Designing Effective Navigation</a>. This lesson discusses how to provide ancestral navigation using the <em>Up</em> button in the action bar.</p> 42 43 44<h2 id="up">Implement <em>Up</em> Navigation</h2> 45 46<p>When implementing ancestral navigation, all screens in your application that aren't the home screen should offer a means of navigating to the immediate parent screen in the hierarchy via the <em>Up</em> button in the action bar.</p> 47 48 49<img src="{@docRoot}images/training/implementing-navigation-up.png" 50 alt="The Up button in the action bar." id="figure-up"> 51 52<p class="img-caption"><strong>Figure 1.</strong> The <em>Up</em> button in the action bar.</p> 53 54<p>Regardless of how the current screen was reached, pressing this button should always take the user to the same screen in the hierarchy.</p> 55 56<p>To implement <em>Up</em>, enable it in the action bar in your activity's {@link android.app.Activity#onCreate onCreate()} method:</p> 57 58<pre> 59{@literal @}Override 60public void onCreate(Bundle savedInstanceState) { 61 ... 62 getActionBar().setDisplayHomeAsUpEnabled(true); 63 ... 64} 65</pre> 66 67<p>You should also handle <code>android.R.id.home</code> in {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. This resource is the menu item ID for the <em>Home</em> (or <em>Up</em>) button. To ensure that a specific parent activity is shown, <em>DO NOT</em> simply call {@link android.app.Activity#finish finish()}. Instead, use an intent such as the one described below.</p> 68 69<pre> 70{@literal @}Override 71public boolean onOptionsItemSelected(MenuItem item) { 72 switch (item.getItemId()) { 73 case android.R.id.home: 74 // This is called when the Home (Up) button is pressed 75 // in the Action Bar. 76 Intent parentActivityIntent = new Intent(this, MyParentActivity.class); 77 parentActivityIntent.addFlags( 78 Intent.FLAG_ACTIVITY_CLEAR_TOP | 79 Intent.FLAG_ACTIVITY_NEW_TASK); 80 startActivity(parentActivityIntent); 81 finish(); 82 return true; 83 } 84 return super.onOptionsItemSelected(item); 85} 86</pre> 87 88<p>When the current activity belongs to a task from a different application—for example if it was reached via an intent from another application—pressing <em>Up</em> should create a new task for the application with a synthesized back stack. This approach is described in <a href="{@docRoot}design/patterns/navigation.html">Android Design: Navigation</a> and the {@link android.support.v4.app.TaskStackBuilder} class reference.</p> 89 90<p>The {@link android.support.v4.app.NavUtils} and {@link android.support.v4.app.TaskStackBuilder} classes in the <a href="{@docRoot}tools/extras/support-library.html">Android Support Package</a> provide helpers for implementing this behavior correctly. An example usage of these two helper classes is below:</p> 91 92<pre> 93{@literal @}Override 94public boolean onOptionsItemSelected(MenuItem item) { 95 switch (item.getItemId()) { 96 case android.R.id.home: 97 Intent upIntent = new Intent(this, MyParentActivity.class); 98 if (NavUtils.shouldUpRecreateTask(this, upIntent)) { 99 // This activity is not part of the application's task, so create a new task 100 // with a synthesized back stack. 101 TaskStackBuilder.from(this) 102 .addNextIntent(new Intent(this, MyGreatGrandParentActivity.class)) 103 .addNextIntent(new Intent(this, MyGrandParentActivity.class)) 104 .addNextIntent(upIntent) 105 .startActivities(); 106 finish(); 107 } else { 108 // This activity is part of the application's task, so simply 109 // navigate up to the hierarchical parent activity. 110 NavUtils.navigateUpTo(this, upIntent); 111 } 112 return true; 113 } 114 return super.onOptionsItemSelected(item); 115} 116</pre> 117 118<h2 id="app-home">Properly Handle the Application Home Screen</h2> 119 120<p>By default, the <em>Home</em> button in the action bar is interactive. Since it does not make much sense to navigate home—or up one level—while on the home screen, you should disable the button like so:</p> 121 122<pre> 123getActionBar().setHomeButtonEnabled(false); 124</pre> 125
