Skip to content

Commit 19266f7

Browse files
romannurikromannurik
committed
docs: Android Training: Implementing Effective Navigation class
Change-Id: Ife2f666e78e3fc0b28ad23321fd98926973e037b
1 parent 6971153 commit 19266f7

File tree

8 files changed

+618
-1
lines changed

8 files changed

+618
-1
lines changed

‎docs/html/images/training/implementing-navigation-up.png‎

8.13 KB
Loading

‎docs/html/resources/resources_toc.cs‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -278,7 +278,32 @@
278278
</a>
279279
</li>
280280
</ul>
281-
</li>
281+
</li>
282+
283+
<li class="toggle-list">
284+
<div><a href="<?cs var:toroot ?>training/implementing-navigation/index.html">
285+
<span class="en">Implementing Effective Navigation<span class="new">&nbsp;new!</span></span>
286+
</a></div>
287+
<ul>
288+
<li><a href="<?cs var:toroot ?>training/implementing-navigation/lateral.html">
289+
<span class="en">Implementing Lateral Navigation</span>
290+
</a>
291+
</li>
292+
<li><a href="<?cs var:toroot ?>training/implementing-navigation/ancestral.html">
293+
<span class="en">Implementing Ancestral Navigation</span>
294+
</a>
295+
</li>
296+
<li><a href="<?cs var:toroot ?>training/implementing-navigation/temporal.html">
297+
<span class="en">Implementing Temporal Navigation</span>
298+
</a>
299+
</li>
300+
<li><a href="<?cs var:toroot ?>training/implementing-navigation/descendant.html">
301+
<span class="en">Implementing Descendant Navigation</span>
302+
</a>
303+
</li>
304+
</ul>
305+
</li>
306+
282307
<li class="toggle-list">
283308
<div><a href="<?cs var:toroot ?>training/tv/index.html">
284309
<span class="en">Designing for TV<span class="new">&nbsp;new!</span></span>

‎docs/html/shareables/training/EffectiveNavigation.zip‎

29.2 KB
Binary file not shown.

‎docs/html/training/implementing-navigation/ancestral.jd‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
page.title=Implementing Ancestral Navigation
2+
parent.title=Implementing Effective Navigation
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
previous.title=Implementing Lateral Navigation
7+
previous.link=lateral.html
8+
next.title=Implementing Temporal Navigation
9+
next.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/topics/fundamentals/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
60+
public 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
71+
public 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&mdash;for example if it was reached via an intent from another application&mdash;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}sdk/compatibility-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
94+
public 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&mdash;or up one level&mdash;while on the home screen, you should disable the button like so:</p>
121+
122+
<pre>
123+
getActionBar().setHomeButtonEnabled(false);
124+
</pre>

‎docs/html/training/implementing-navigation/descendant.jd‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
page.title=Implementing Descendant Navigation
2+
parent.title=Implementing Effective Navigation
3+
parent.link=index.html
4+
5+
trainingnavtop=true
6+
previous.title=Implementing Temporal Navigation
7+
previous.link=temporal.html
8+
9+
@jd:body
10+
11+
<div id="tb-wrapper">
12+
<div id="tb">
13+
14+
<h2>This lesson teaches you to:</h2>
15+
<ol>
16+
<li><a href="#master-detail">Implement Master/Detail Flows Across Handsets and Tablets</a></li>
17+
<li><a href="#external-activities">Navigate into External Activities</a></li>
18+
</ol>
19+
20+
<h2>You should also read</h2>
21+
<ul>
22+
<li><a href="{@docRoot}training/design-navigation/descendant-lateral.html">Providing Descendant and Lateral Navigation</a></li>
23+
<li><a href="{@docRoot}design/patterns/app-structure.html">Android Design: App Structure</a></li>
24+
<li><a href="{@docRoot}design/patterns/multi-pane-layouts.html">Android Design: Multi-pane Layouts</a></li>
25+
</ul>
26+
27+
<h2>Try it out</h2>
28+
29+
<div class="download-box">
30+
<a href="http://developer.android.com/shareables/training/EffectiveNavigation.zip"
31+
class="button">Download the sample app</a>
32+
<p class="filename">EffectiveNavigation.zip</p>
33+
</div>
34+
35+
</div>
36+
</div>
37+
38+
39+
<p><em>Descendant navigation</em> is navigation down the application's information hierarchy. This is described in <a href="{@docRoot}training/design-navigation/descendant-lateral.html">Designing Effective Navigation</a> and also covered in <a href="{@docRoot}design/patterns/app-structure.html">Android Design: Application Structure</a>.</p>
40+
41+
<p>Descendant navigation is usually implemented using {@link android.content.Intent} objects and {@link android.content.Context#startActivity startActivity()}, or by adding fragments to an activity using {@link android.app.FragmentTransaction} objects. This lesson covers other interesting cases that arise when implementing descendant navigation.</p>
42+
43+
<h2 id="master-detail">Implement Master/Detail Flows Across Handsets and Tablets</h2>
44+
45+
<p>In a <em>master/detail</em> navigation flow, a <em>master</em> screen contains a list of items in a collection, and a <em>detail</em> screen shows detailed information about a specific item within that collection. Implementing navigation from the master screen to the detail screen is one form of descendant navigation.</p>
46+
47+
<p>Handset touchscreens are most suitable for displaying one screen at a time (either the master or the detail screen); this concern is further discussed in <a href="{@docRoot}training/design-navigation/multiple-sizes.html">Planning for Multiple Touchscreen Sizes</a>. Descendant navigation in this case is often implemented using an {@link android.content.Intent} that starts an activity representing the detail screen. On the other hand, tablet displays, especially when viewed in the landscape orientation, are best suited for showing multiple content panes at a time: the master on the left, and the detail to the right). Here, descendant navigation is usually implemented using a {@link android.app.FragmentTransaction} that adds, removes, or replaces the detail pane with new content.</p>
48+
49+
<p>The basics of implementing this pattern are described in the <a href="{@docRoot}training/multiscreen/adaptui.html">Implementing Adaptive UI Flows</a> lesson of the <em>Designing for Multiple Screens</em> class. The class describes how to implement a master/detail flow using two activities on a handset and a single activity on a tablet.</p>
50+
51+
<h2 id="external-activities">Navigate into External Activities</h2>
52+
53+
<p>There are cases where descending into your application's information hierarchy leads to activities from other applications. For example, when viewing the contact details screen for an entry in the phone address book, a child screen detailing recent posts by the contact on a social network may belong to a social networking application.</p>
54+
55+
<p>When launching another application's activity to allow the user to say, compose an email or pick a photo attachment, you generally don't want the user to return to this activity if they relaunch your application from the Launcher (the device home screen). It would be confusing if touching your application icon brought the user to a "compose email" screen.</p>
56+
57+
<p>To prevent this from occurring, simply add the {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET} flag to the intent used to launch the external activity, like so:</p>
58+
59+
<pre>
60+
Intent externalActivityIntent = new Intent(Intent.ACTION_PICK);
61+
externalActivityIntent.setType("image/*");
62+
externalActivityIntent.addFlags(
63+
Intent.FLAG_ACTIVITY_CLEAR_WHEN_TASK_RESET);
64+
startActivity(externalActivityIntent);
65+
</pre>

‎docs/html/training/implementing-navigation/index.jd‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
page.title=Implementing Effective Navigation
2+
3+
trainingnavtop=true
4+
startpage=true
5+
next.title=Implementing Lateral Navigation
6+
next.link=lateral.html
7+
8+
@jd:body
9+
10+
<div id="tb-wrapper">
11+
<div id="tb">
12+
13+
<h2>Dependencies and prerequisites</h2>
14+
15+
<ul>
16+
<li>API level 14</li>
17+
<li>Understanding of fragments and Android layouts</li>
18+
<li><a href="{@docRoot}sdk/compatibility-library.html">The Android Support Package</a></li>
19+
<li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a></li>
20+
</ul>
21+
22+
<h2>You should also read</h2>
23+
24+
<ul>
25+
<li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li>
26+
<li><a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a></li>
27+
<li><a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a></li>
28+
</ul>
29+
30+
<h2>Try it out</h2>
31+
32+
<div class="download-box">
33+
<a href="http://developer.android.com/shareables/training/EffectiveNavigation.zip"
34+
class="button">Download the sample app</a>
35+
<p class="filename">EffectiveNavigation.zip</p>
36+
</div>
37+
38+
</div>
39+
</div>
40+
41+
42+
<p>This class demonstrates how to implement the key navigation design patterns detailed in the
43+
<a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a> class.
44+
The lessons in this class cover implementing navigation up, down, and across your application's <a
45+
href="{@docRoot}training/design-navigation/screen-planning.html#diagram- relationships">screen
46+
map</a>.</p>
47+
48+
<p>After reading through the lessons in this class and exploring the associated sample application
49+
(see right), you should also have a basic understanding of how to use
50+
{@link android.app.ActionBar} and {@link android.support.v4.view.ViewPager}, two components that are fundamental to core app navigation.</p>
51+
52+
53+
<h2 id="lessons">Lessons</h2>
54+
55+
56+
<dl>
57+
<dt><strong><a href="lateral.html">Implementing Lateral Navigation</a></strong></dt>
58+
<dd>Learn how to implement tabs and horizontal paging (swipe views).</dd>
59+
60+
<dt><strong><a href="ancestral.html">Implementing Ancestral Navigation</a></strong></dt>
61+
<dd>Learn how to implement <em>Up</em> navigation.</dd>
62+
63+
<dt><strong><a href="temporal.html">Implementing Temporal Navigation</a></strong></dt>
64+
<dd>Learn how to correctly handle the <em>Back</em> button.</dd>
65+
66+
<dt><strong><a href="descendant.html">Implementing Descendant Navigation</a></strong></dt>
67+
<dd>Learn the finer points of implementing navigation into your application's information hierarchy.</dd>
68+
</dl>

0 commit comments

Comments
 (0)