diff options
76 files changed, 1643 insertions, 557 deletions
diff --git a/docs/downloads/training/NavigationDrawer.zip b/docs/downloads/training/NavigationDrawer.zip Binary files differnew file mode 100644 index 0000000..3375a5c --- /dev/null +++ b/docs/downloads/training/NavigationDrawer.zip diff --git a/docs/html/design/building-blocks/buttons.jd b/docs/html/design/building-blocks/buttons.jd index 600ec6c..7957ef8 100644 --- a/docs/html/design/building-blocks/buttons.jd +++ b/docs/html/design/building-blocks/buttons.jd @@ -2,6 +2,13 @@ page.title=Buttons page.tags="button","input" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/button.html"> + <div> + <h3>Developer Docs</h3> + <p>Buttons</p> + </div> +</a> + <p>A button consists of text and/or an image that clearly communicates what action will occur when the user touches it. Android supports two different types of buttons: <em>basic buttons</em> and <em>borderless buttons</em>. Both can contain text labels and/or images.</p> @@ -38,9 +45,3 @@ than basic buttons and integrate nicely with other content.</p> <img src="{@docRoot}design/media/buttons_borderless.png"> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build and customize buttons in your app, - see the <a href="{@docRoot}guide/topics/ui/controls/button.html">Buttons</a> API guide.</p> -</div> diff --git a/docs/html/design/building-blocks/dialogs.jd b/docs/html/design/building-blocks/dialogs.jd index 2f6ca27..f4bb87e 100644 --- a/docs/html/design/building-blocks/dialogs.jd +++ b/docs/html/design/building-blocks/dialogs.jd @@ -2,6 +2,13 @@ page.title=Dialogs page.tags="dialog","alert","popup","toast" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/dialogs.html"> + <div> + <h3>Developer Docs</h3> + <p>Dialogs</p> + </div> +</a> + <p>Dialogs prompt the user for decisions or additional information required by the app to continue a task. Such requests can range from simple Cancel/OK decisions to more complex layouts asking the user to adjust settings or enter text.</p> @@ -123,11 +130,6 @@ available based on the title and the text of the action buttons.</p> </div> </div> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build dialogs in your app, - see the <a href="{@docRoot}guide/topics/ui/dialogs.html">Dialogs</a> API guide.</p> -</div> <h2 id="popups">Popups</h2> @@ -144,12 +146,19 @@ advances the workflow, and simply touching outside the popup dismisses it.</p> <div class="layout-content-row"> <div class="layout-content-col span-6"> - <div class="vspace size-6"></div> + <div class="vspace size-3"></div> <p>Toasts provide lightweight feedback about an operation in a small popup. For example, navigating away from an email before you send it triggers a "Draft saved" toast to let you know that you can continue editing later. Toasts automatically disappear after a timeout.</p> +<a class="notice-developers left" href="{@docRoot}guide/topics/ui/notifiers/toasts.html"> + <div> + <h3>Developer Docs</h3> + <p>Toasts</p> + </div> +</a> + </div> <div class="layout-content-col span-7"> @@ -158,9 +167,3 @@ continue editing later. Toasts automatically disappear after a timeout.</p> </div> </div> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create toasts, - see the <a href="{@docRoot}guide/topics/ui/notifiers/toasts.html">Toasts</a> API guide.</p> -</div> diff --git a/docs/html/design/building-blocks/grid-lists.jd b/docs/html/design/building-blocks/grid-lists.jd index 8c82ba9..1a09ef5 100644 --- a/docs/html/design/building-blocks/grid-lists.jd +++ b/docs/html/design/building-blocks/grid-lists.jd @@ -4,6 +4,13 @@ page.tags="gridview","layout","listview" <img src="{@docRoot}design/media/gridview_overview.png"> +<a class="notice-developers" href="{@docRoot}guide/topics/ui/layout/gridview.html"> + <div> + <h3>Developer Docs</h3> + <p>Grid View</p> + </div> +</a> + <p>Grid lists are an alternative to standard list views. They are best suited for showing data sets that represent themselves through images. In contrast to simple lists, grid lists may scroll either vertically or horizontally.</p> diff --git a/docs/html/design/building-blocks/lists.jd b/docs/html/design/building-blocks/lists.jd index 16927a6..5514824 100644 --- a/docs/html/design/building-blocks/lists.jd +++ b/docs/html/design/building-blocks/lists.jd @@ -2,6 +2,13 @@ page.title=Lists page.tags="listview","layout" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/layout/listview.html"> + <div> + <h3>Developer Docs</h3> + <p>List View</p> + </div> +</a> + <p>Lists present multiple line items in a vertical arrangement. They can be used for data selection as well as drilldown navigation.</p> diff --git a/docs/html/design/building-blocks/pickers.jd b/docs/html/design/building-blocks/pickers.jd index 47363d0..6dd72ba 100644 --- a/docs/html/design/building-blocks/pickers.jd +++ b/docs/html/design/building-blocks/pickers.jd @@ -2,6 +2,13 @@ page.title=Pickers page.tags="datepicker","timepicker" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/pickers.html"> + <div> + <h3>Developer Docs</h3> + <p>Pickers</p> + </div> +</a> + <p>Pickers provide a simple way to select a single value from a set. In addition to touching the up/down arrow buttons, it's possible to set the desired value from the keyboard or via a swipe gesture.</p> @@ -31,9 +38,3 @@ correctly. The format of a time and date picker adjusts automatically to the loc <img src="{@docRoot}design/media/picker_datetime.png"> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create date and time pickers, - see the <a href="{@docRoot}guide/topics/ui/controls/pickers.html">Pickers</a> API guide.</p> -</div> diff --git a/docs/html/design/building-blocks/spinners.jd b/docs/html/design/building-blocks/spinners.jd index 3550b0c..c00b639 100644 --- a/docs/html/design/building-blocks/spinners.jd +++ b/docs/html/design/building-blocks/spinners.jd @@ -2,6 +2,13 @@ page.title=Spinners page.tags="spinner","dropdown" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/spinner.html"> + <div> + <h3>Developer Docs</h3> + <p>Spinners</p> + </div> +</a> + <p>Spinners provide a quick way to select one value from a set. In the default state, a spinner shows its currently selected value. Touching the spinner displays a dropdown menu with all other available values, from which the user can select a new one.</p> @@ -37,9 +44,3 @@ tabs.</p> Spinners in the Holo Dark and Holo Light themes, in various states. </div> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create spinners, - see the <a href="{@docRoot}guide/topics/ui/controls/spinner.html">Spinners</a> API guide.</p> -</div> diff --git a/docs/html/design/building-blocks/switches.jd b/docs/html/design/building-blocks/switches.jd index 0b195b9..74cab5a 100644 --- a/docs/html/design/building-blocks/switches.jd +++ b/docs/html/design/building-blocks/switches.jd @@ -4,31 +4,53 @@ page.tags="switch","checkbox","radiobutton","button" <p>Switches allow the user to select options. There are three kinds of switches: checkboxes, radio buttons, and on/off switches.</p> + + + <h2 id="checkboxes">Checkboxes</h2> +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/checkbox.html"> + <div> + <h3>Developer Docs</h3> + <p>Checkboxes</p> + </div> +</a> + <p>Checkboxes allow the user to select multiple options from a set. Avoid using a single checkbox to turn an option off or on. Instead, use an on/off switch.</p> <img src="{@docRoot}design/media/switches_checkboxes.png"> + + <h2 id="radio-buttons">Radio Buttons</h2> +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/radiobutton.html"> + <div> + <h3>Developer Docs</h3> + <p>Radio Buttons</p> + </div> +</a> + <p>Radio buttons allow the user to select one option from a set. Use radio buttons for exclusive selection if you think that the user needs to see all available options side-by-side. Otherwise, consider a spinner, which uses less space.</p> <img src="{@docRoot}design/media/switches_radios.png"> + + <h2 id="switches">On/off Switches</h2> +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/togglebutton.html"> + <div> + <h3>Developer Docs</h3> + <p>Toggle Buttons</p> + </div> +</a> + <p>On/off switches toggle the state of a single settings option.</p> <img src="{@docRoot}design/media/switches_switches.png"> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create these different switches, - see the <a href="{@docRoot}guide/topics/ui/controls/checkbox.html">Checkboxes</a>, - <a href="{@docRoot}guide/topics/ui/controls/radiobutton.html">Radio Buttons</a>, or - <a href="{@docRoot}guide/topics/ui/controls/togglebutton.html">Toggle Buttons</a> API guides.</p> -</div> + diff --git a/docs/html/design/building-blocks/tabs.jd b/docs/html/design/building-blocks/tabs.jd index 79cc9c7..4778400 100644 --- a/docs/html/design/building-blocks/tabs.jd +++ b/docs/html/design/building-blocks/tabs.jd @@ -4,6 +4,13 @@ page.tags="tabs","actionbar","navigation","viewpager" <img src="{@docRoot}design/media/tabs_overview.png"> +<a class="notice-developers" href="{@docRoot}training/implementing-navigation/lateral.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating Swipe Views with Tabs</p> + </div> +</a> + <p>Tabs in the action bar make it easy to explore and switch between different views or functional aspects of your app, or to browse categorized data sets.</p> @@ -59,9 +66,3 @@ permits fast view switching even on narrower screens.</p> <img src="{@docRoot}design/media/tabs_stacked.png"> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create tabs, - see the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API guide.</p> -</div> diff --git a/docs/html/design/building-blocks/text-fields.jd b/docs/html/design/building-blocks/text-fields.jd index 82321f0..383531b 100644 --- a/docs/html/design/building-blocks/text-fields.jd +++ b/docs/html/design/building-blocks/text-fields.jd @@ -2,6 +2,13 @@ page.title=Text Fields page.tags="text","edittext","input" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/controls/text.html"> + <div> + <h3>Developer Docs</h3> + <p>Text Fields</p> + </div> +</a> + <p>Text fields allow the user to type text into your app. They can be either single line or multi-line. Touching a text field places the cursor and automatically displays the keyboard. In addition to typing, text fields allow for a variety of other activities, such as text selection (cut, copy, @@ -70,10 +77,3 @@ Selection mode includes:</p> </div> </div> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create text fields, provide auto-complete suggestions, - and specify the input mode, - see the <a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a> API guide.</p> -</div> diff --git a/docs/html/design/design_toc.cs b/docs/html/design/design_toc.cs index c3020e1..ff465bf 100644 --- a/docs/html/design/design_toc.cs +++ b/docs/html/design/design_toc.cs @@ -31,6 +31,7 @@ <li><a href="<?cs var:toroot ?>design/patterns/app-structure.html">App Structure</a></li> <li><a href="<?cs var:toroot ?>design/patterns/navigation.html">Navigation</a></li> <li><a href="<?cs var:toroot ?>design/patterns/actionbar.html">Action Bar</a></li> + <li><a href="<?cs var:toroot ?>design/patterns/navigation-drawer.html">Navigation Drawer</a></li> <li><a href="<?cs var:toroot ?>design/patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> <li><a href="<?cs var:toroot ?>design/patterns/swipe-views.html">Swipe Views</a></li> <li><a href="<?cs var:toroot ?>design/patterns/selection.html">Selection</a></li> diff --git a/docs/html/design/media/actionbar_drawer.png b/docs/html/design/media/actionbar_drawer.png Binary files differdeleted file mode 100644 index 95e04f5..0000000 --- a/docs/html/design/media/actionbar_drawer.png +++ /dev/null diff --git a/docs/html/design/media/action_bar_pattern_default_tabs.png b/docs/html/design/media/app_structure_default_tabs.png Binary files differindex a6d0d90..a6d0d90 100644 --- a/docs/html/design/media/action_bar_pattern_default_tabs.png +++ b/docs/html/design/media/app_structure_default_tabs.png diff --git a/docs/html/design/media/app_structure_drawer.png b/docs/html/design/media/app_structure_drawer.png Binary files differnew file mode 100644 index 0000000..560e834 --- /dev/null +++ b/docs/html/design/media/app_structure_drawer.png diff --git a/docs/html/design/media/action_bar_pattern_spinner.png b/docs/html/design/media/app_structure_spinner.png Binary files differindex 9aff412..9aff412 100644 --- a/docs/html/design/media/action_bar_pattern_spinner.png +++ b/docs/html/design/media/app_structure_spinner.png diff --git a/docs/html/design/media/navigation_between_apps_back.png b/docs/html/design/media/navigation_between_apps_back.png Binary files differindex d5cd979..d5cd979 100755..100644 --- a/docs/html/design/media/navigation_between_apps_back.png +++ b/docs/html/design/media/navigation_between_apps_back.png diff --git a/docs/html/design/media/navigation_between_apps_inward.png b/docs/html/design/media/navigation_between_apps_inward.png Binary files differindex 7394b1c..7394b1c 100755..100644 --- a/docs/html/design/media/navigation_between_apps_inward.png +++ b/docs/html/design/media/navigation_between_apps_inward.png diff --git a/docs/html/design/media/navigation_between_apps_up.png b/docs/html/design/media/navigation_between_apps_up.png Binary files differindex 99c3112..99c3112 100755..100644 --- a/docs/html/design/media/navigation_between_apps_up.png +++ b/docs/html/design/media/navigation_between_apps_up.png diff --git a/docs/html/design/media/navigation_between_siblings_market1.png b/docs/html/design/media/navigation_between_siblings_market1.png Binary files differindex b12a432..b12a432 100755..100644 --- a/docs/html/design/media/navigation_between_siblings_market1.png +++ b/docs/html/design/media/navigation_between_siblings_market1.png diff --git a/docs/html/design/media/navigation_between_siblings_market2.png b/docs/html/design/media/navigation_between_siblings_market2.png Binary files differindex a09d9d7..a09d9d7 100755..100644 --- a/docs/html/design/media/navigation_between_siblings_market2.png +++ b/docs/html/design/media/navigation_between_siblings_market2.png diff --git a/docs/html/design/media/navigation_drawer_CAB.png b/docs/html/design/media/navigation_drawer_CAB.png Binary files differnew file mode 100644 index 0000000..9d4a5b5 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_CAB.png diff --git a/docs/html/design/media/navigation_drawer_collapse.png b/docs/html/design/media/navigation_drawer_collapse.png Binary files differnew file mode 100644 index 0000000..7ca56da --- /dev/null +++ b/docs/html/design/media/navigation_drawer_collapse.png diff --git a/docs/html/design/media/navigation_drawer_cross_nav.png b/docs/html/design/media/navigation_drawer_cross_nav.png Binary files differnew file mode 100644 index 0000000..bf8d238 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_cross_nav.png diff --git a/docs/html/design/media/navigation_drawer_first_run.png b/docs/html/design/media/navigation_drawer_first_run.png Binary files differnew file mode 100644 index 0000000..728f29f --- /dev/null +++ b/docs/html/design/media/navigation_drawer_first_run.png diff --git a/docs/html/design/media/navigation_drawer_holo_dark_light.png b/docs/html/design/media/navigation_drawer_holo_dark_light.png Binary files differnew file mode 100644 index 0000000..dcb91ab --- /dev/null +++ b/docs/html/design/media/navigation_drawer_holo_dark_light.png diff --git a/docs/html/design/media/navigation_drawer_indicator_big.png b/docs/html/design/media/navigation_drawer_indicator_big.png Binary files differnew file mode 100644 index 0000000..5faa93b --- /dev/null +++ b/docs/html/design/media/navigation_drawer_indicator_big.png diff --git a/docs/html/design/media/navigation_drawer_layout.png b/docs/html/design/media/navigation_drawer_layout.png Binary files differnew file mode 100644 index 0000000..e59b37c --- /dev/null +++ b/docs/html/design/media/navigation_drawer_layout.png diff --git a/docs/html/design/media/navigation_drawer_nav_and_actions.png b/docs/html/design/media/navigation_drawer_nav_and_actions.png Binary files differnew file mode 100644 index 0000000..0df04e9 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_nav_and_actions.png diff --git a/docs/html/design/media/navigation_drawer_navigation_hubs.png b/docs/html/design/media/navigation_drawer_navigation_hubs.png Binary files differnew file mode 100644 index 0000000..9f4b244 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_navigation_hubs.png diff --git a/docs/html/design/media/navigation_drawer_open_from_lower.png b/docs/html/design/media/navigation_drawer_open_from_lower.png Binary files differnew file mode 100644 index 0000000..ec5f03d --- /dev/null +++ b/docs/html/design/media/navigation_drawer_open_from_lower.png diff --git a/docs/html/design/media/navigation_drawer_open_overflow.png b/docs/html/design/media/navigation_drawer_open_overflow.png Binary files differnew file mode 100644 index 0000000..112a414 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_open_overflow.png diff --git a/docs/html/design/media/navigation_drawer_overview.png b/docs/html/design/media/navigation_drawer_overview.png Binary files differnew file mode 100644 index 0000000..42d21fa --- /dev/null +++ b/docs/html/design/media/navigation_drawer_overview.png diff --git a/docs/html/design/media/navigation_drawer_peek.png b/docs/html/design/media/navigation_drawer_peek.png Binary files differnew file mode 100644 index 0000000..c59881e --- /dev/null +++ b/docs/html/design/media/navigation_drawer_peek.png diff --git a/docs/html/design/media/navigation_drawer_quick_to_top.png b/docs/html/design/media/navigation_drawer_quick_to_top.png Binary files differnew file mode 100644 index 0000000..0e44915 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_quick_to_top.png diff --git a/docs/html/design/media/navigation_drawer_reset_backstack.png b/docs/html/design/media/navigation_drawer_reset_backstack.png Binary files differnew file mode 100644 index 0000000..c0c2f61 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_reset_backstack.png diff --git a/docs/html/design/media/navigation_drawer_settings_help.png b/docs/html/design/media/navigation_drawer_settings_help.png Binary files differnew file mode 100644 index 0000000..ed29971 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_settings_help.png diff --git a/docs/html/design/media/navigation_drawer_titles_icons.png b/docs/html/design/media/navigation_drawer_titles_icons.png Binary files differnew file mode 100644 index 0000000..b726c9b --- /dev/null +++ b/docs/html/design/media/navigation_drawer_titles_icons.png diff --git a/docs/html/design/media/navigation_drawer_top_out.png b/docs/html/design/media/navigation_drawer_top_out.png Binary files differnew file mode 100644 index 0000000..ad92b77 --- /dev/null +++ b/docs/html/design/media/navigation_drawer_top_out.png diff --git a/docs/html/design/patterns/accessibility.jd b/docs/html/design/patterns/accessibility.jd index 5f46082..16a39d6 100644 --- a/docs/html/design/patterns/accessibility.jd +++ b/docs/html/design/patterns/accessibility.jd @@ -2,6 +2,13 @@ page.title=Accessibility page.tags="accessibility","navigation","input" @jd:body +<a class="notice-developers" href="{@docRoot}training/accessibility/index.html"> + <div> + <h3>Developer Docs</h3> + <p>Implementing Accessibility</p> + </div> +</a> + <p>One of Android's missions is to organize the world's information and make it universally accessible and useful. Accessibility is the measure of how successfully a product can be used by people with varying abilities. Our mission applies to all users-including people with disabilities such as visual impairment, color deficiency, hearing loss, and limited dexterity.</p> <p><a href="https://www.google.com/#hl=en&q=universal+design&fp=1">Universal design</a> is the practice of making products that are inherently accessible to all users, regardless of ability. The Android design patterns were created in accordance with universal design principles, and following them will help your app meet basic usability standards. Adhering to universal design and enabling Android's accessibility tools will make your app as accessible as possible.</p> <p>Robust support for accessibility will increase your app's user base. It may also be required for adoption by some organizations.</p> @@ -71,13 +78,6 @@ page.tags="accessibility","navigation","input" <p>Turn on the TalkBack service in <strong>Settings > Accessibility</strong> and navigate your application using directional controls or eyes-free navigation.</p> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to properly implement accessibility in your app, see the - <a href="{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a> - API guide.</p> -</div> - <h2>Checklist</h2> <ul> diff --git a/docs/html/design/patterns/actionbar.jd b/docs/html/design/patterns/actionbar.jd index da9c3c3..6020034 100644 --- a/docs/html/design/patterns/actionbar.jd +++ b/docs/html/design/patterns/actionbar.jd @@ -4,6 +4,14 @@ page.tags="actionbar","navigation" <img src="{@docRoot}design/media/action_bar_pattern_overview.png"> +<a class="notice-developers" href="{@docRoot}guide/topics/ui/actionbar.html"> + <div> + <h3>Developer Docs</h3> + <p>Action Bar</p> + </div> +</a> + + <p>The <em>action bar</em> is a dedicated piece of real estate at the top of each screen that is generally persistent throughout the app.</p> <p><strong>It provides several key functions</strong>:</p> <ul> @@ -48,7 +56,7 @@ Up navigation, see the <a href="{@docRoot}design/patterns/navigation.html">Navig <p> If your app displays data in different views, this segment of the action bar allows users to switch -views. Examples of view-switching controls are drop-down menus or tab controls. +views. Examples of view-switching controls are drop-down menus or tab controls. For more information on view-switching, see the <a href="{@docRoot}design/patterns/app-structure.html">App Structure</a> pattern. </p> <p> @@ -115,132 +123,11 @@ the top bar.</p> </div> </div> -<h2 id="contextual">Contextual Action Bars</h2> - -<p>A <em>contextual action bar (CAB)</em> is a temporary action bar that overlays the app's action bar for the -duration of a particular sub-task. CABs are most typically used for tasks that involve acting on -selected data or text.</p> - -<img src="{@docRoot}design/media/action_bar_cab.png"> -<div class="figure-caption"> - Contextual action bar shown in Browser and Gmail -</div> - -<p>The selection CAB appears after a long press on a selectable data item triggers selection mode.</p> -<p><strong>From here the user can</strong>:</p> -<ul> -<li>Select additional elements by touching them.</li> -<li>Trigger an action from the CAB that applies to all selected data items. The CAB then - automatically dismisses itself.</li> -<li>Dismiss the CAB via the navigation bar's Back button or the CAB's checkmark button. This removes - the CAB along with all selection highlights.</li> -</ul> -<p>Use CABs whenever you allow the user to select data via long press. You can control the action -content of a CAB in order to insert the actions you would like the user to be able to perform.</p> -<p>For more information, refer to the <a href="{@docRoot}design/patterns/selection.html">Selection -pattern</a>.</p> - -<h2 id="elements">View Controls</h2> -<p>If your app displays data in different views, the action bar has three different controls to allow users to switch between them: tabs, spinners, and drawers.</p> - -<h4>Tabs</h4> -<p><em>Tabs</em> display app views concurrently and make it easy to explore and switch between them. Tabs may be fixed, where all tabs are simultaneously displayed, or may scroll, allowing a larger number of views to be presented.</p> - -<img src="{@docRoot}design/media/tabs_youtube.png"> - -<p><strong>Use tabs if</strong>:</p> -<ul> -<li>You expect your app's users to switch views frequently.</li> -<li>You want the user to be highly aware of the alternate views.</li> -</ul> - -<h4>Fixed tabs</h4> -<div class="layout-content-row"> - <div class="layout-content-col span-6"> -<p><em>Fixed tabs</em> are always visible on the screen, and can't be moved out of the way like scrollable -tabs. Fixed tabs in the main action bar can move to the top bar when the screen orientation changes.</p> - -<p>Use fixed tabs to support quick changes between two or three app views. Fixed tabs should always allow the user to navigate between the views by swiping left or right on the content area.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="{@docRoot}design/media/action_bar_pattern_default_tabs.png"> - <div class="figure-caption"> - Default fixed tabs shown in Holo Dark & Light. - </div> - - </div> -</div> - -<h4>Scrollable tabs</h4> -<div class="layout-content-row"> - <div class="layout-content-col span-6"> -<p><em>Scrollable tabs</em> always take up the entire width of the bar, with the currently active view item in the center, and therefore need to live in a dedicated bar. Scrollable tabs can themselves be scrolled horizontally to bring more tabs into view.</p> -<p>Use scrollable tabs if you have a large number of views or if you're unsure how many views will be displayed because your app inserts views dynamically (for example, open chats in a messaging app that the user can navigate between). Scrollable tabs should always allow the user to navigate between the views by swiping left or right on the content area as well as swiping the tabs themselves.</p> - - </div> - <div class="layout-content-col span-7"> - - <video width="400" class="with-shadow play-on-hover" autoplay> - <source src="{@docRoot}design/media/tabs_scrolly.mp4" type="video/mp4"> - <source src="{@docRoot}design/media/tabs_scrolly.webm" type="video/webm"> - <source src="{@docRoot}design/media/tabs_scrolly.ogv" type="video/ogg"> - </video> - <div class="figure-caption"> - Scrolling tabs in the Play Store app. - <div class="video-instructions"> </div> - </div> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Spinners</h4> -<p>A <em>spinner</em> is a drop-down menu that allows users to switch between views of your app. </p> -<p><strong>Use a spinner in the main action bar if</strong>:</p> -<ul> -<li>You don't want to give up the vertical screen real estate for a dedicated tab bar.</li> -<li>The user is switching between views of the same data set (for example: calendar events viewed by day, week, or month) or data sets of the same type (such as content for two different accounts).</li> -</ul> - - </div> - <div class="layout-content-col span-7"> - - <img src="{@docRoot}design/media/action_bar_pattern_spinner.png"> - <div class="figure-caption"> - Action bar spinner from Calendar application. - </div> - - </div> -</div> - -<h4>Drawers</h4> -<div class="layout-content-row"> - <div class="layout-content-col span-6"> -<p>A <em>drawer</em> is a slide-out menu that allows users to switch between views of your app. It can be opened by touching the action bar's app icon (decorated with the Up caret.) Additionally, a drawer can be revealed by an edge swipe from the left of the screen, and dismissed by swiping from the right edge of the drawer. However, because many users will rely on Up navigation to open a drawer, it is only suitable for use at the topmost level of your app's hierarchy.</p> - -<p><strong>Open a drawer from the main action bar if</strong>:</p> -<ul> -<li>You don't want to give up the vertical screen real estate for a dedicated tab bar.</li> -<li>You want to provide direct navigation to a number of views within your app which don't have direct relationships between each other.</li> -</ul> - - </div> - <div class="layout-content-col span-7"> - <img src="{@docRoot}design/media/actionbar_drawer.png"> - </div> -</div> - -<h2>Action buttons</h2> +<h2>Action Buttons</h2> <p><em>Action buttons</em> on the action bar surface your app's most important activities. Think about which buttons will get used most often, and order them accordingly. Depending on available screen real estate, the system shows your most important actions as action buttons and moves the rest to the -action overflow. The action bar and the action overflow should only present actions to the user that -are available. If an action is unavailable in the current context, hide it. Do not show it as -disabled.</p> +action overflow. The action bar should show only those actions that are available to the user. If an action is unavailable in the current context, hide it. Do not show it as disabled.</p> <img src="{@docRoot}design/media/action_bar_pattern_action_icons.png"> <div class="figure-caption"> @@ -350,16 +237,32 @@ sharing options.</p> The Gallery app's share action provider with extended spinner for additional sharing options. </div> +<h2 id="contextual">Contextual Action Bars</h2> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build an action bar - see the <a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> API guide. - For information about contextual action bars, read - <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Creating Contextual Menus</a>. - </p> +<p>A <em>contextual action bar (CAB)</em> is a temporary action bar that overlays the app's action bar for the +duration of a particular sub-task. CABs are most typically used for tasks that involve acting on +selected data or text.</p> + +<img src="{@docRoot}design/media/action_bar_cab.png"> +<div class="figure-caption"> + Contextual action bar in Browser and Gmail </div> +<p>The selection CAB appears after a long press on a selectable data item triggers selection mode.</p> +<p><strong>From here the user can</strong>:</p> +<ul> +<li>Select additional elements by touching them.</li> +<li>Trigger an action from the CAB that applies to all selected data items. The CAB then + automatically dismisses itself.</li> +<li>Dismiss the CAB via the navigation bar's Back button or the CAB's checkmark button. This removes + the CAB along with all selection highlights.</li> +</ul> +<p>Use CABs whenever you allow the user to select data via long press. You can control the action +content of a CAB in order to insert the actions you would like the user to be able to perform.</p> +<p>For more information, refer to the <a href="{@docRoot}design/patterns/selection.html">Selection +pattern</a>.</p> + + <h2 id="checklist">Action Bar Checklist</h2> @@ -374,4 +277,4 @@ actions exceeds the capacity of the main action bar, display them separately in <p>Sometimes it is important to display contextual information for your app that's always visible. Examples are the number of unread messages in a messaging inbox view or the Now Playing information in a music player. Carefully plan which important information you would like to display and -structure your action bars accordingly.</p> +structure your action bars accordingly.</p>
\ No newline at end of file diff --git a/docs/html/design/patterns/app-structure.jd b/docs/html/design/patterns/app-structure.jd index 1809ecd..0dc20e2 100644 --- a/docs/html/design/patterns/app-structure.jd +++ b/docs/html/design/patterns/app-structure.jd @@ -2,7 +2,7 @@ page.title=Application Structure page.tags="navigation","layout","tablet" @jd:body -<p>Apps come in many varieties that address very different needs. For example:</p> + <p>Apps come in many varieties that address very different needs. For example:</p> <ul> <li>Apps such as Calculator or Camera that are built around a single focused activity handled from a single screen</li> @@ -62,7 +62,7 @@ layouts that are visually engaging and appropriate for the data type and screen <img src="{@docRoot}design/media/app_structure_market.png"> <div class="figure-caption"> The Play Store app's start screen primarily allows navigation into the stores for Apps, Music, Books, - Movies and Games. It is also enriched with tailored recommendations and promotions that + Movies, and Games. It is also enriched with tailored recommendations and promotions that surface content of interest to the user. Search is readily available from the action bar. </div> @@ -72,23 +72,40 @@ layouts that are visually engaging and appropriate for the data type and screen <div class="layout-content-row"> <div class="layout-content-col span-5"> +<h4>Create an identity for your app</h4> +<p>Creating an identity for your app goes beyond the action bar. Your app communicates its identity +through its data, the way that data is arranged, and how people interact with it. Especially for +media-rich applications, try to create unique layouts that showcase your data and go beyond the +monotony of simple list views.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/app_structure_music_lndscp.png"> + <div class="figure-caption"> + The 3D carousel celebrates cover art and establishes a unique identity for the Music app. + Defaulting to the Recent view keeps the focus on music the user has been listening to lately. + </div> + + </div> +</div> + <h4>Set up action bars for navigation and actions</h4> -<p>All screens in your app should display action bars to provide consistent navigation and surface + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + + <p>All screens in your app should display action bars to provide consistent navigation and surface important actions.</p> -<p>At the top level, special considerations apply to the action bar:</p> -<ul> -<li>Use the action bar to display your app's icon or title.</li> -<li>If your top level consists of multiple views, or if switching between data from different user - accounts is a significant use case, make sure that it's easy for the user to navigate between them - by adding view controls to your action bar.</li> -<li>If your app allows people to create content, consider making the content accessible right from the + <p>At the top level, special considerations apply to the action bar:</p> + <ul> + <li>Use the action bar to display your app's icon or title.</li> + <li>If your top level consists of multiple views, make sure that it's easy for the user to navigate between them by adding view controls to your action bar.</li> + <li>If your app allows people to create content, consider making the content accessible right from the top level.</li> -<li>If your content is searchable, include the Search action in the action bar so people can cut + <li>If your content is searchable, include the Search action in the action bar so people can cut through the navigation hierarchy.</li> -</ul> - -<p>For more discussion, see the <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> -design guide.</p> + </ul> </div> <div class="layout-content-col span-8"> @@ -103,27 +120,79 @@ design guide.</p> </div> </div> +<h2 id="top-level-switching">Top Level Switching With View Controls</h2> +<p>The top level communicates your app’s capabilities by introducing the user to the major functional areas. In many cases the top level will consist of multiple views, and you need to make sure that the user can navigate between them efficiently. Android supports a number of view controls for this task. Use the control that best matches your app's navigation needs:</p> + +<h4>Fixed tabs</h4> <div class="layout-content-row"> - <div class="layout-content-col span-5"> + <div class="layout-content-col span-6"> +<p><em>Fixed tabs</em> display top-level views concurrently and make it easy to explore and switch between them. They are always visible on the screen, and can't be moved out of the way like scrollable tabs. <em>Fixed tabs</em> should always allow the user to navigate between the views by swiping left or right on the content area.</p> +<p><strong>Use tabs if</strong>:</p> +<ul> +<li>You expect your app's users to switch views frequently.</li> +<li>You have a limited number of up to three top-level views.</li> +<li>You want the user to be highly aware of the alternate views.</li> +</ul> -<h4>Create an identity for your app</h4> -<p>Creating an identity for your app goes beyond the action bar. Your app communicates its identity -through its data, the way that data is arranged, and how people interact with it. Especially for -media-rich applications, try to create unique layouts that showcase your data and go beyond the -monotony of simple list views.</p> + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/app_structure_default_tabs.png"> + <div class="figure-caption"> + Default fixed tabs shown in Holo Dark & Light. + </div> </div> - <div class="layout-content-col span-8"> +</div> - <img src="{@docRoot}design/media/app_structure_music_lndscp.png"> +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Spinners</h4> +<p>A <em>spinner</em> is a drop-down menu that allows users to switch between views of your app. </p> +<p><strong>Use a spinner in the main action bar if</strong>:</p> +<ul> +<li>You don't want to give up the vertical screen real estate for a dedicated tab bar.</li> +<li>The user is switching between views of the same data set (for example: calendar events viewed by day, week, or month) or data sets of the same type (such as content for two different accounts).</li> +</ul> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/app_structure_spinner.png"> <div class="figure-caption"> - The 3D carousel celebrates cover art and establishes a unique identity for the Music app. - Defaulting to the Recent view keeps the focus on music the user has been listening to lately. + Action bar spinner from Calendar application. </div> </div> </div> +<h4>Navigation drawers</h4> +<div class="layout-content-row"> + <div class="layout-content-col span-6"> +<p>A <em>navigation drawer</em> is a slide-out menu that allows users to switch between views of your app. It can hold a large number of items and is accessible from anywhere in your app. Navigation drawers show your app's top-level views, but can also provide navigation to lower-level screens. This makes them particularly suitable for complex apps.</p> + +<p><strong>Use navigation drawers if</strong>:</p> +<ul> +<li>You don't want to give up the vertical screen real estate for a dedicated tab bar.</li> +<li>You have a large number of top-level views.</li> +<li>You want to provide direct access to screens on lower levels.</li> +<li>You want to provide quick navigation to views which don't have direct relationships between each other.</li> +<li>You have particularly deep navigation branches.</li> +</ul> + + </div> + <div class="layout-content-col span-7"> + <img src="{@docRoot}design/media/app_structure_drawer.png"> + <div class="figure-caption"> + Navigation drawer from the Shopper app. + </div> + </div> +</div> + +<h4>Don't mix and match</h4> +<p>After choosing the best top-level navigation for your app, don't mix and match patterns. For example, if you decide to use tabs for top-level switching, don't add a drawer, even if your navigation branches are deep. In this case, the navigation drawer would simply duplicate the information on the tabs, confusing your users.</p> + <h2 id="categories">Categories</h2> <p>Generally, the purpose of a deep, data-driven app is to navigate through organizational categories @@ -275,4 +344,4 @@ design guide.</p> <li> <p>Allow for quick navigation between detail items with swipe views.</p> </li> -</ul> +</ul>
\ No newline at end of file diff --git a/docs/html/design/patterns/compatibility.jd b/docs/html/design/patterns/compatibility.jd index 3a56f52..5ca6d8b 100644 --- a/docs/html/design/patterns/compatibility.jd +++ b/docs/html/design/patterns/compatibility.jd @@ -2,6 +2,13 @@ page.title=Backwards Compatibility page.tags="support" @jd:body +<a class="notice-developers" href="{@docRoot}training/basics/supporting-devices/index.html"> + <div> + <h3>Developer Docs</h3> + <p>Supporting Different Devices</p> + </div> +</a> + <p>Significant changes in Android 3.0 included:</p> <ul> <li>Deprecation of navigation hardware keys (Back, Menu, Search, Home) in favor of handling navigation diff --git a/docs/html/design/patterns/multi-pane-layouts.jd b/docs/html/design/patterns/multi-pane-layouts.jd index cbf29cb..06c8189 100644 --- a/docs/html/design/patterns/multi-pane-layouts.jd +++ b/docs/html/design/patterns/multi-pane-layouts.jd @@ -2,6 +2,14 @@ page.title=Multi-pane Layouts page.tags="tablet","navigation","layout","fragment" @jd:body + +<a class="notice-developers" href="{@docRoot}training/basics/fragments/index.html"> + <div> + <h3>Developer Docs</h3> + <p>Building a Dynamic UI with Fragments</p> + </div> +</a> + <p>When writing an app for Android, keep in mind that Android devices come in many different screen sizes and types. Make sure that your app consistently provides a balanced and aesthetically pleasing layout by adjusting its content to varying screen sizes and orientations.</p> @@ -88,15 +96,6 @@ you can use to adjust the layout after orientation change while keeping function </div> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create multi-pane layouts, read - see the <a href="{@docRoot}training/basics/fragments/index.html">Building - a Dynamic UI with Fragments</a> and - <a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a>. - </p> -</div> - <h2 id="checklist">Checklist</h2> diff --git a/docs/html/design/patterns/navigation-drawer.jd b/docs/html/design/patterns/navigation-drawer.jd new file mode 100644 index 0000000..bf6609e --- /dev/null +++ b/docs/html/design/patterns/navigation-drawer.jd @@ -0,0 +1,338 @@ +page.title=Navigation Drawer +page.tags="DrawerLayout","SlidingPaneLayout" +@jd:body + + +<a class="notice-developers" href="{@docRoot}training/implementing-navigation/nav-drawer.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating a Navigation Drawer</p> + </div> +</a> + + +<p>The navigation drawer is a panel that transitions in from the left edge of the screen and +displays the app’s main navigation options.</p> + + +<h4>Displaying the navigation drawer</h4> + +<p>The user can bring the navigation drawer onto the screen by swiping from the left edge of the +screen or by touching the application icon on the action bar.</p> + +<p>As the navigation drawer expands, it overlays the content but not the action bar. When the +drawer is fully extended, the action bar adjusts its content by replacing the current action +bar title with the app name and removing all actions that are contextual to the view underneath +the navigation drawer. The overflow menu with the standard action items for Settings and Help +remains visible.</p> + +<img src="{@docRoot}design/media/navigation_drawer_overview.png"> +<div class="figure-caption"> + The user can open the drawer panel by touching the navigation drawer indicator. +</div> + +<p>Because they are transient, navigation drawers make views less cluttered. You can also use +them at deeper levels in the navigation hierarchy, allowing users to switch to your app's most +important screens from anywhere in the app.</p> + +<img src="{@docRoot}design/media/navigation_drawer_open_from_lower.png"> +<div class="figure-caption"> + Open the drawer from anywhere in your app by swiping from the left edge of the screen. +</div> + + +<h4>Dismissing the navigation drawer</h4> + +<p> When the navigation drawer is expanded, the user can dismiss it in one of four ways: </p> +<ul> + <li>Touching the content outside the navigation drawer</li> + <li>Swiping to the left anywhere on the screen (including edge swipe from right)</li> + <li>Touching the app icon/title in the action bar</li> + <li>Pressing Back</li> +</ul> + + +<h2 id="WhenToUse"> When to Use the Navigation Drawer </h2> + +<p> The navigation drawer is not a general replacement for top-level navigation via spinners +or tabs. The structure of your app should guide your choice of which pattern to use for +top-level switching. For more information on top-level switching mechanisms, see the +<a href="{@docRoot}design/patterns/app-structure.html">Application Structure</a> design pattern.</p> +<p> Here are some examples of where navigation drawers work best:</p> + +<h4>More than 3 top-level views</h4> +<p> Navigation drawers are great for displaying a large number of navigation targets +concurrently. Use the navigation drawer if you have more than 3 unique top-level views. +If not, use fixed tabs for top-level organization to ease discovery and interaction.</p> + +<h4>Cross-navigation from lower levels</h4> +<p> If your app requires cross-navigating between lower-level screens, consider using the +navigation drawer. Because it is accessible from anywhere in the app, the drawer enables +efficient navigation from lower-level screens to other important places in your app.</p> + +<img src="{@docRoot}design/media/navigation_drawer_cross_nav.png"> +<div class="figure-caption"> + The navigation drawer makes cross-navigation at lower levels possible. +</div> + + +<h4>Deep navigation branches</h4> +<p> If you have particularly deep branches, navigating to the top-level of your app can become +repetitive and cumbersome with Up and Back alone. Since navigation drawers are accessible from +anywhere in the app, navigation up to the top level is faster and more efficient.</p> + +<img src="{@docRoot}design/media/navigation_drawer_quick_to_top.png"> +<div class="figure-caption"> + The navigation drawer allows for quick jumps to the top-level of your app, removing the need + for repetitive Back or Up sequences. +</div> + + +<h2 id="Hubs">Navigation Hubs</h2> + +<p>The navigation drawer is a reflection of your app’s structure and displays its major +navigation hubs. Think of navigation hubs as those places in your app that a user will want +to visit frequently or use as a jumping-off point to other parts of the app. +At a minimum, the navigation hubs are the top-level views, since they correspond to your app’s +major functional areas.</p> +<p> If your app’s structure is deep, you can add screens from lower levels that your users will +likely visit often and make those navigation hubs as well.</p> + +<img src="{@docRoot}design/media/navigation_drawer_navigation_hubs.png"> +<div class="figure-caption"> + The navigation drawer contains all of your app's navigation hubs. Include your top level + screens as well as important lower-level screens. +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + <p> To facilitate access to the navigation drawer on navigation hubs, all screens that + correspond to an entry in your navigation drawer should show the navigation drawer indicator + next to the application icon in the action bar. Touching the app icon causes the navigation + drawer to slide in from the left. </p> + <p> All other lower-level screens show the traditional Up indicator next to the application + icon. The drawer is still accessible with an edge-swipe, but is not featured in the action bar.</p> + </div> + <div class="layout-content-col span-5"> + <img src="{@docRoot}design/media/navigation_drawer_indicator_big.png"> + <div class="figure-caption"> + App icon with navigation drawer indicator. + </div> + </div> +</div> + + +<h2 id="Content">Content of the Navigation Drawer</h2> + +<p> Keep the content of the navigation drawer focused on app navigation. Expose the navigation +hubs of your app as list items inside the navigation drawer - one item per row. + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + <h4>Titles, icons, and counters</h4> + <p> You can structure navigation targets by adding titles. The titles are not interactive, + but just organize navigation targets into functional topics. If you have many navigation + targets, use titles to orient the user within the drawer.</p> + <p> Navigation targets can have optional leading icons as well as trailing counters. Use + the counters to inform users about a changed state of data in the corresponding view.</p> + </div> + <div class="layout-content-col span-5"> + <img src="{@docRoot}design/media/navigation_drawer_titles_icons.png"> + <div class="figure-caption"> + Use titles and icons to organize your drawer. + </div> + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + <img src="{@docRoot}design/media/navigation_drawer_collapse.png"> + <div class="figure-caption"> + Collapsible navigation items are split. Use the left side for navigation and the right + to collapse and expand items. + </div> + </div> + <div class="layout-content-col span-5"> + <h4>Collapsible navigation items</h4> + <p>If you have many views with some subordinate to others, consider collapsing them into one + expandable item to conserve space. + The parent in the navigation drawer then turns into a split item. The left side allows + navigation to the parent item’s view, and the right side collapses or expands the list of + child items. </p> + <p> At launch, the initial state of the collapsible items is up to you. As a rule, all + top-level view entries of the navigation drawer should be visible. If you have many collapsible + items, consider collapsing all items to allow the user to see the top-level views in their + entirety.</p> + <p> When the user opens the drawer from a lower-level screen, expand the associated branch + of the top-level view to give a stronger sense of place and highlight navigation opportunities + close to the user’s current + location in the app.</p> + </div> +</div> + + +<h2 id="ActionBar">Navigation Drawers and Action Bars</h2> + +<p> When the user expands the navigation drawer, the task focus switches to selecting an item +from the drawer. Because the drawer does not overlay the action bar, users may not realize that +the items in the action bar do not pertain to the navigation drawer. </p> +<p> To reduce confusion, adjust the content of the action bar to the following, once the drawer +is fully expanded:</p> +<ul> + <li>App icon</li> + <li>App name</li> + <li>Remove actions from the action bar that are contextual to the underlying view (such as + Create new, Refresh). You may retain actions with global scope, such as “Search”.</li> + <li>Overflow menu with expected navigation targets, such as Settings and Help.</li> +</ul> + +<img src="{@docRoot}design/media/navigation_drawer_open_overflow.png"> +<div class="figure-caption"> + Clean up the action bar when the drawer is fully expanded. Remove actions that are not needed + and display your app's name in the title area. +</div> + +<h4>Actions</h4> +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + <img src="{@docRoot}design/media/navigation_drawer_nav_and_actions.png"> + <div class="figure-caption"> + Keep actions on the right side of the action bar and in the overflow + </div> + </div> + <div class="layout-content-col span-6"> + <p> Don’t place actions in the navigation drawer. Actions belong in the action bar, and the + user expects to see them there. Keep in mind that not all applications use the navigation + drawer pattern. It may be tempting to expose all your app’s capabilities in a single place, + but keep the bigger picture in mind. Place your actions where all apps display them.</p> + </div> +</div> +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + <p> This also applies to common navigation targets, such as access to Help or the app’s + Settings. As per style guide convention Help and Settings are always located in the action + overflow.</p> + </div> + <div class="layout-content-col span-6"> + <img src="{@docRoot}design/media/navigation_drawer_settings_help.png"> + <div class="figure-caption"> + Keep Help and Settings in the overflow. + </div> + </div> +</div> + + +<h4>Contextual action bars</h4> +<p> Sometimes the user will be in a state where a contextual action bar (CAB) appears instead +of the app’s action bar. This typically happens when the user selects text or selects multiple +items after a press-and-hold gesture. While the CAB is visible, you should still allow the +user to open the navigation drawer using an edge swipe. However, replace the CAB with the +standard action bar while the navigation drawer is open. When the user dismisses the drawer, +re-display the CAB.</p> + +<img src="{@docRoot}design/media/navigation_drawer_CAB.png"> +<div class="figure-caption"> + Hide contextual action bars while the drawer is visible. +</div> + +<p>If the user navigates away from a view with selected content, deselect the content before +before navigating to the new view.</p> + + +<h2 id="Interaction">Interaction Details</h2> + +<h4>Introduce the user to the drawer at first use</h4> +<p> Upon first launch of your app, introduce the user to the navigation drawer by +automatically opening it. This ensures that users know about the navigation drawer and prompts +them to learn about the structure of your app by exploring its content. Continue showing the +drawer upon subsequent launches until the user actively expands the navigation drawer manually. +Once you know that the user understands how to open the drawer, launch the app with the +navigation drawer closed. </p> + +<img src="{@docRoot}design/media/navigation_drawer_first_run.png"> +<div class="figure-caption"> + At first use, show the navigation drawer automatically to help the user learn the + functionality and structure of your app. +</div> + +<h4>Give the user a quick peek</h4> +<p> If the user touches the very left edge of the screen (within 20 dp from the left), have the +drawer peek out as soon as the finger makes contact with the display. This promotes accidental +discovery and provides richer feedback. </p> + +<img src="{@docRoot}design/media/navigation_drawer_peek.png"> +<div class="figure-caption"> + The navigation drawer peeks out when the user touches the very left edge of the screen. +</div> + +<h4>Highlights</h4> +<p> When you open the navigation drawer from a screen that is represented inside the drawer, +highlight its entry in the drawer. Vice versa, if you open the drawer from a screen that is +not listed in the drawer, none of the items of the drawer should be highlighted.</p> + + +<h2 id="ImpactOnNav">Impact of Drawer on Overall App Navigation</h2> + +<p>The navigation drawer is an alternative to other top-level navigation patterns. To make apps +with navigation drawers work consistently with apps that use a tab or spinner pattern, remember +that all navigation requirements for system Back and Up apply.</p> +<p>Pay special attention to the following situations:</p> + +<h4>System Back at the top level of the app</h4> +<p>Touching System Back at the app’s top level never opens the navigation drawer. Instead, +System Back behaves according to the navigation rules for the top level, such as navigating +to the previous app within the task or navigating to the Home screen.</p> + +<img src="{@docRoot}design/media/navigation_drawer_top_out.png"> +<div class="figure-caption"> + System Back does not show the drawer, but behaves according to the navigation rules for + the top level. +</div> + +<h4>System Back after cross navigation to lower hierarchy levels</h4> +<p>If the user navigates to a lower hierarchy screen from the navigation drawer and the screen +has a direct parent, then the Back stack is reset and Back points to the target screen’s parent. +This Back behavior is the same as when a user navigates into an app from a notification.</p> + +<img src="{@docRoot}design/media/navigation_drawer_reset_backstack.png"> +<div class="figure-caption"> + Reset the Back stack if your lower-level navigation target has direct parents. +</div> + + +<h2 id="Style">Style</h2> + +<p>The width of the navigation drawer depends on the content you want to display, but should be +between a minimum of 240 dp and a maximum of 320 dp. The height of the individual line items +should not fall below 48 dp. See the layout guideline below for recommendations on padding and +spacing.</p> + +<img src="{@docRoot}design/media/navigation_drawer_layout.png"> +<div class="figure-caption"> + Layout guidelines for the navigation drawer. +</div> + + +<p>Pick the drawer background to best match your app’s theme. See the following examples +for a Holo light and a Holo dark themed drawer.</p> + +<img src="{@docRoot}design/media/navigation_drawer_holo_dark_light.png"> +<div class="figure-caption"> + Navigation drawers in Holo light and Holo dark themed apps. +</div> + + +<h2 id="Checklist">Navigation Drawer Checklist</h2> + +<p>Even if you already support a similar navigation drawer, update your drawer to this +pattern to make sure that:</p> +<ul> + <li>The action bar remains in place and adjusts its content.</li> + <li>Your navigation drawer overlays the content.</li> + <li>Any view represented in the drawer has a navigation drawer indicator in its action bar + that allows the drawer to be opened by touching the app icon.</li> + <li>You take advantage of the new visual drawer transition.</li> + <li>Any view not represented in the drawer maintains the traditional Up indicator in its action bar.</li> + <li>You stay in sync with the general navigation patterns for Up and Back.</li> +</ul> + diff --git a/docs/html/design/patterns/navigation.jd b/docs/html/design/patterns/navigation.jd index b717884..4da87b9 100644 --- a/docs/html/design/patterns/navigation.jd +++ b/docs/html/design/patterns/navigation.jd @@ -2,6 +2,13 @@ page.title=Navigation with Back and Up page.tags="navigation","activity","task" @jd:body +<a class="notice-developers" href="{@docRoot}training/implementing-navigation/index.html"> + <div> + <h3>Developer Docs</h3> + <p>Implementing Effective Navigation</p> + </div> +</a> + <p>Consistent navigation is an essential component of the overall user experience. Few things frustrate users more than basic navigation that behaves in inconsistent and unexpected ways. Android 3.0 introduced significant changes to the global navigation behavior. Thoughtfully following the @@ -203,15 +210,3 @@ with Task B—the prior context is abandoned in favor of the user's new goal <p>When your app registers to handle intents with an activity deep within the app's hierarchy, refer to <a href="#into-your-app">Navigation into Your App via Home Screen Widgets and Notifications</a> for guidance on how to specify Up navigation.</p> - - - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build your app with proper Up and Back navigation, read - <a href="{@docRoot}training/implementing-navigation/ancestral.html">Implementing - Ancestral Navigation</a> and - <a href="{@docRoot}training/implementing-navigation/temporal.html">Implementing - Temporal Navigation</a>, respectively. - </p> -</div> diff --git a/docs/html/design/patterns/notifications.jd b/docs/html/design/patterns/notifications.jd index 3ae827e..018b7b9 100644 --- a/docs/html/design/patterns/notifications.jd +++ b/docs/html/design/patterns/notifications.jd @@ -1,7 +1,13 @@ page.title=Notifications -page.tags="notification" @jd:body +<a class="notice-developers" href="{@docRoot}training/notify-user/index.html"> + <div> + <h3>Developer Docs</h3> + <p>Notifying the User</p> + </div> +</a> + <p>The notification system allows your app to keep the user informed about events, such as new chat messages or a calendar event. Think of notifications as a news channel that alerts the user to important events as they happen or a log that chronicles events while the user is not paying attention.</p> <h4>New in Jelly Bean</h4> @@ -258,11 +264,3 @@ develop a widget that they can choose to place on their home screen.</p> </div> </div> - - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build notifications, see the - <a href="{@docRoot}guide/topics/ui/notifiers/notifications.html">Notifications</a> - API guide.</p> -</div> diff --git a/docs/html/design/patterns/selection.jd b/docs/html/design/patterns/selection.jd index d16e86c..973ffde 100644 --- a/docs/html/design/patterns/selection.jd +++ b/docs/html/design/patterns/selection.jd @@ -2,6 +2,13 @@ page.title=Selection page.tags="actionmode","navigation","contextual" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/menus.html#context-menu"> + <div> + <h3>Developer Docs</h3> + <p>Menus: Creating Contextual Menus</p> + </div> +</a> + <p>Android 3.0 changed the <em>long press</em> gesture—that is, a touch that's held in the same position for a moment—to be the global gesture to select data.. This affects the way you should handle multi-select and contextual actions in your apps.</p> diff --git a/docs/html/design/patterns/settings.jd b/docs/html/design/patterns/settings.jd index 4748e48..fa3e538 100644 --- a/docs/html/design/patterns/settings.jd +++ b/docs/html/design/patterns/settings.jd @@ -2,6 +2,13 @@ page.title=Settings page.tags="preferences","sharedpreferences" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/ui/settings.html"> + <div> + <h3>Developer Docs</h3> + <p>Settings</p> + </div> +</a> + <p>Settings is a place in your app where users indicate their preferences for how your app should behave. This benefits users because:</p> @@ -681,13 +688,6 @@ it doesn't mean anything to most users and would have taken up a lot of space.</ </div> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build a settings interface, see the - <a href="{@docRoot}guide/topics/ui/settings.html">Settings</a> - API guide.</p> -</div> - <h2 id="checklist">Checklist</h2> <ul> diff --git a/docs/html/design/patterns/swipe-views.jd b/docs/html/design/patterns/swipe-views.jd index f18fc63..630a4b9 100644 --- a/docs/html/design/patterns/swipe-views.jd +++ b/docs/html/design/patterns/swipe-views.jd @@ -2,6 +2,13 @@ page.title=Swipe Views page.tags="viewpager","navigation","tabs" @jd:body +<a class="notice-developers" href="{@docRoot}training/implementing-navigation/lateral.html"> + <div> + <h3>Developer Docs</h3> + <p>Creating Swipe Views with Tabs</p> + </div> +</a> + <p>Efficient navigation is one of the cornerstones of a well-designed app. While apps are generally built in a hierarchical fashion, there are instances where horizontal navigation can flatten vertical hierarchies and make access to related data items faster and more enjoyable. Swipe views @@ -79,12 +86,3 @@ using the swipe gesture to navigate to the next/previous detail view.</p> </div> </div> - -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to create swipe views, read - <a href="{@docRoot}training/implementing-navigation/lateral.html">Implementing Lateral Navigation</a>. - </p> -</div> - - diff --git a/docs/html/design/patterns/widgets.jd b/docs/html/design/patterns/widgets.jd index 3152e91..87ebbb9 100644 --- a/docs/html/design/patterns/widgets.jd +++ b/docs/html/design/patterns/widgets.jd @@ -2,6 +2,13 @@ page.title=Widgets page.tags="appwidget","home" @jd:body +<a class="notice-developers" href="{@docRoot}guide/topics/appwidgets/index.html"> + <div> + <h3>Developer Docs</h3> + <p>App Widgets</p> + </div> +</a> + <p>Widgets are an essential aspect of home screen customization. You can imagine them as "at-a-glance" views of an app's most important data and functionality that is accessible right from the user's home screen. Users can move widgets across their home screen panels, and, if supported, resize them to tailor the amount of information within a widget to their preference.</p> <h2>Widget types</h2> @@ -124,13 +131,6 @@ A music player widget is primarily a control widget, but also keeps the user inf </div> -<div class="note develop"> -<p><strong>Developer Guide</strong></p> - <p>For information about how to build widgets for the home screen, see the - <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a> - API guide.</p> -</div> - <h2>Checklist</h2> <ul> <li>Focus on small portions of glanceable information on your widget. Expand on the information in your app.</li> diff --git a/docs/html/google/backup/signup.jd b/docs/html/google/backup/signup.jd index 70f7de2..550d590 100644 --- a/docs/html/google/backup/signup.jd +++ b/docs/html/google/backup/signup.jd @@ -1,4 +1,5 @@ page.title=Register for Android Backup Service +excludeFromSuggestions=true @jd:body diff --git a/docs/html/google/backup/terms.jd b/docs/html/google/backup/terms.jd index decb0d8..e5b00a4 100644 --- a/docs/html/google/backup/terms.jd +++ b/docs/html/google/backup/terms.jd @@ -1,4 +1,5 @@ page.title=Android Backup Service Terms of Service +excludeFromSuggestions=true @jd:body diff --git a/docs/html/google/gcm/index.jd b/docs/html/google/gcm/index.jd index f9c3ed3..aeba86f 100644 --- a/docs/html/google/gcm/index.jd +++ b/docs/html/google/gcm/index.jd @@ -1,10 +1,11 @@ page.title=Google Cloud Messaging for Android +page.tags="gcm" header.hide=1 @jd:body <div class="landing-banner"> - + <div class="col-5" style="min-height:100px"> <img src="{@docRoot}images/gcm/gcm-logo.png" /> </div> @@ -15,7 +16,7 @@ header.hide=1 Google Cloud Messaging for Android (GCM) is a service that allows you to send data from your server to your users' Android-powered device, and also to receive messages from devices on the same connection. The GCM service handles all aspects of queueing of messages and delivery to the target Android application running on the target device. GCM is completely free no matter how big your messaging needs are, and there are no quotas. </p> - + </div> </div> @@ -27,12 +28,12 @@ from your server to your users' Android-powered device, and also to receive mess message telling your app there is new data to be fetched from the server (for instance, a movie uploaded by a friend), or it could be a message containing up to 4kb of payload data (so apps like instant messaging can consume the message directly). <a href="{@docRoot}google/gcm/gcm.html">GCM Architectural Overview.</a></p> - + <h4>Send "send-to-sync" messages</h4> - <p>A send-to-sync (collapsible) message is often a "tickle" that tells a mobile application to sync data from the server. For example, suppose you have an email application. When a user receives new email on the server, the server pings the mobile application with a "New mail" message. This tells the application to sync to the server to pick up the new email. + <p>A send-to-sync (collapsible) message is often a "tickle" that tells a mobile application to sync data from the server. For example, suppose you have an email application. When a user receives new email on the server, the server pings the mobile application with a "New mail" message. This tells the application to sync to the server to pick up the new email. <a href="{@docRoot}google/gcm/adv.html#s2s">Send-to-sync messages</a>.</p> </a> - + <h4>Send messages with payload</h4> <p>Unlike a send-to-sync message, every "message with payload" (non-collapsible message) is delivered. The payload the message contains can be up to 4kb. <a href="{@docRoot}google/gcm/adv.html#payload">Messages with payload</a>.</p> @@ -45,7 +46,7 @@ up to 4kb of payload data (so apps like instant messaging can consume the messag <p>Streamlined registration makes it simple and fast to add GCM support to your Android app. <a href="{@docRoot}google/gcm/gs.html">Learn more »</a></p> <h4>Upstream messaging over XMPP</h4> <p>GCM's Cloud Connection Service (CCS) lets you communicate with Android devices over a persistent XMPP connection. The primary advantages of CCS are speed, and the ability to receive upstream messages (that is, messages from a device to the cloud). You can use the service in tandem with existing GCM APIs. Use <a href="https://services.google.com/fb/forms/gcm/">this form</a> to sign up for CCS. <a href="{@docRoot}google/gcm/ccs.html">Learn more »</a></p> - + <h4>Seamless multi-device messaging</h4> <p>Maps a single user to a notification key, which you can then use to send a single message to multiple devices owned by the user. Use <a href="https://services.google.com/fb/forms/gcm/">this form</a> to sign up for User Notifications. <a href="{@docRoot}google/gcm/notifications.html">Learn more »</a></p> </div> diff --git a/docs/html/google/play-services/location.jd b/docs/html/google/play-services/location.jd index ddaa890..1cdd247 100644 --- a/docs/html/google/play-services/location.jd +++ b/docs/html/google/play-services/location.jd @@ -1,5 +1,5 @@ page.title=Location APIs -page.tags="location","geofence", "geofencing", "activity recognition", "activity detection", "gps" +page.tags="location","geofence", "geofencing", "gps" header.hide=1 @jd:body @@ -93,4 +93,4 @@ header.hide=1 </li> </ul> </div> -</div>
\ No newline at end of file +</div> diff --git a/docs/html/guide/appendix/media-formats.jd b/docs/html/guide/appendix/media-formats.jd index feacdc6..2342087 100644 --- a/docs/html/guide/appendix/media-formats.jd +++ b/docs/html/guide/appendix/media-formats.jd @@ -1,4 +1,5 @@ page.title=Android Supported Media Formats +page.tags="video","audio","mpeg","mp4","m4a","mp3","3gp","3gpp","flac","wave","wav" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/guide/topics/location/strategies.jd b/docs/html/guide/topics/location/strategies.jd index f5f61a0..f1eb66e 100644 --- a/docs/html/guide/topics/location/strategies.jd +++ b/docs/html/guide/topics/location/strategies.jd @@ -1,7 +1,5 @@ page.title=Location Strategies excludeFromSuggestions=true -page.tags="geolocation","maps","mapview" - @jd:body <div id="tb-wrapper"> diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd index 8ebb349..e48109a 100644 --- a/docs/html/guide/topics/media/camera.jd +++ b/docs/html/guide/topics/media/camera.jd @@ -1,5 +1,5 @@ page.title=Camera -page.tags="mediarecorder" +page.tags="photo","video","picture","mediarecorder" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/sdk/exploring.jd b/docs/html/sdk/exploring.jd index e8d8e37..9323f2e 100644 --- a/docs/html/sdk/exploring.jd +++ b/docs/html/sdk/exploring.jd @@ -1,4 +1,5 @@ page.title=Exploring the SDK +excludeFromSuggestions=true walkthru=1 @jd:body diff --git a/docs/html/sdk/installing/installing-adt.jd b/docs/html/sdk/installing/installing-adt.jd index 8d47f4e..4286db1 100644 --- a/docs/html/sdk/installing/installing-adt.jd +++ b/docs/html/sdk/installing/installing-adt.jd @@ -106,13 +106,13 @@ href="{@docRoot}distribute/googleplay/publish/localizing.html#gp-trans">Purchase <li>In Eclipse, select <strong>Help</strong> > <strong>Install New Software</strong>.</li> <li>Click <strong>Add</strong>, in the top-right corner.</li> - <li>In the Add Repository dialog that appears, enter "Translation Manager Plugin" for the <em>Name</em> and the -following URL for the <em>Location</em>: + <li>In the Add Repository dialog that appears, enter a repository name for the <em>Name</em> + and the following URL for the <em>Location</em>: <pre>https://dl.google.com/alt/</pre> </li> <li>Click <strong>OK</strong>. - <li>In the Available Software dialog, select the checkbox next to Translation Manager Plugin and click -<strong>Next</strong>.</li> + <li>In the Available Software dialog, select the checkbox next to <strong>Android Developer Tools + - Translation Manager</strong> and click <strong>Next</strong>.</li> <li>In the next window, you'll see a list of the tools to be downloaded. Click <strong>Next</strong>. </li> <li>Read and accept the license agreements, then click <strong>Finish</strong>. diff --git a/docs/html/sdk/installing/studio.jd b/docs/html/sdk/installing/studio.jd index 856121a..c79b3a7 100644 --- a/docs/html/sdk/installing/studio.jd +++ b/docs/html/sdk/installing/studio.jd @@ -1,4 +1,5 @@ page.title=Getting Started with Android Studio +page.tags="studio" @jd:body diff --git a/docs/html/tools/adk/adk.jd b/docs/html/tools/adk/adk.jd index 049b6e9..1651747 100644 --- a/docs/html/tools/adk/adk.jd +++ b/docs/html/tools/adk/adk.jd @@ -1,4 +1,5 @@ page.title=Accessory Development Kit 2011 Guide +page.tags="adk" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/tools/adk/adk2.jd b/docs/html/tools/adk/adk2.jd index 0b18583..c60e920 100644 --- a/docs/html/tools/adk/adk2.jd +++ b/docs/html/tools/adk/adk2.jd @@ -1,4 +1,5 @@ page.title=Accessory Development Kit 2012 Guide +page.tags="adk" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/tools/adk/index.jd b/docs/html/tools/adk/index.jd index d492e96..e035115 100644 --- a/docs/html/tools/adk/index.jd +++ b/docs/html/tools/adk/index.jd @@ -1,4 +1,5 @@ page.title=Accessory Development Kit +page.tags="adk" @jd:body <p>The Accessory Development Kit (ADK) is a reference implementation for hardware manufacturers and diff --git a/docs/html/tools/extras/support-library.jd b/docs/html/tools/extras/support-library.jd index 6475e3c..0ec6592 100644 --- a/docs/html/tools/extras/support-library.jd +++ b/docs/html/tools/extras/support-library.jd @@ -49,6 +49,45 @@ the Support Package, as denoted by revision number.</p> <div class="toggle-content opened"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" +/>Support Package, revision 13</a> <em>(May 2013)</em> + </p> + <div class="toggle-content-toggleme"> + <dl> + <dt>Changes for v4 support library:</dt> + <dd> + <ul> + <li>Added {@link android.support.v4.widget.DrawerLayout} for creating a + <a href="{@docRoot}training/implementing-navigation/nav-drawer.html">Navigation + Drawer</a> that can be pulled in from the edge of a window.</li> + <li>Added {@link android.support.v4.widget.SlidingPaneLayout} widget for creating linked + summary and detail views that appropriately adapt to various screen sizes.</li> + <li>Added {@link android.support.v4.app.ActionBarDrawerToggle} as a way to tie + together the functions of {@link android.support.v4.widget.DrawerLayout} and {@link + android.app.ActionBar}.</li> + <li>Added {@link android.support.v4.widget.ViewDragHelper} as a new common component + for dragging views within a parent view.</li> + <li>Added {@link android.support.v4.widget.ScrollerCompat} to provide {@link + android.widget.Scroller} and {@link android.widget.OverScroller} compatibility support. + </li> + <li>Updated {@link android.support.v4.view.ViewPager} to throw an exception if the + associated {@link android.support.v4.view.PagerAdapter} class is modified without a call + to {@link android.support.v4.view.PagerAdapter#notifyDataSetChanged notifyDataSetChanged()}. + </li> + <li>Fixed an issue with {@link android.support.v4.view.ViewPager} children drawing sort + order.</li> + <li>Fixed {@link android.support.v4.view.GestureDetectorCompat} to dispatch missing + {@link android.view.GestureDetector.SimpleOnGestureListener#onSingleTapConfirmed} calls + between tap timeout and long press events.</li> + </ul> + </dd> + </dl> + </div> +</div> + + +<div class="toggle-content closed"> + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" />Support Package, revision 12</a> <em>(February 2013)</em> </p> <div class="toggle-content-toggleme"> diff --git a/docs/html/tools/help/adb.jd b/docs/html/tools/help/adb.jd index c8afca5..74f6c07 100644 --- a/docs/html/tools/help/adb.jd +++ b/docs/html/tools/help/adb.jd @@ -1,6 +1,7 @@ page.title=Android Debug Bridge parent.title=Tools parent.link=index.html +page.tags="adb" @jd:body <div id="qv-wrapper"> @@ -101,10 +102,10 @@ option to specify the target device to which the command should be directed. </p <p class="table-caption"><strong>Table 1.</strong> Available adb commands</p> <table> <tr> - <th>Category</th> - <th>Command</th> - <th>Description</th> - <th>Comments</th> + <th>Category</th> + <th>Command</th> + <th>Description</th> + <th>Comments</th> </tr> <tr> @@ -191,7 +192,7 @@ Commands to a Specific Emulator/Device Instance</a>.</td> <td rowspan="2">Ports and Networking</td> <td><code>forward <local> <remote></code></td> <td>Forwards socket connections from a specified local port to a specified remote port on the emulator/device instance. </td> -<td>Port specifications can use these schemes: +<td>Port specifications can use these schemes: <ul><li><code>tcp:<portnum></code></li> <li><code>local:<UNIX domain socket name></code></li> <li><code>dev:<character device name></code></li> @@ -226,10 +227,10 @@ Commands to a Specific Emulator/Device Instance</a>.</td> <tr> <td><code>wait-for-device</code></td> <td>Blocks execution until the device is online — that is, until the instance state is <code>device</code>.</td> -<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example: +<td>You can prepend this command to other adb commands, in which case adb will wait until the emulator/device instance is connected before issuing the other commands. Here's an example: <pre class="no-pretty-print">adb wait-for-device shell getprop</pre> -Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as +Note that this command does <em>not</em> cause adb to wait until the entire system is fully booted. For that reason, you should not prepend it to other commands that require a fully booted system. As an example, the <code>install</code> requires the Android package manager, which is available only after the system is fully booted. A command such as <pre class="no-pretty-print">adb wait-for-device install <app>.apk</pre> @@ -280,34 +281,34 @@ would issue the <code>install</code> command as soon as the emulator or device i <p>Before issuing adb commands, it is helpful to know what emulator/device instances are connected to the adb server. You can generate a list of attached emulators/devices using the <code>devices</code> command: </p> - <pre class="no-pretty-print">adb devices</pre> + <pre class="no-pretty-print">adb devices</pre> <p>In response, adb prints this status information for each instance:</p> <ul> - <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its - console port number. The format of the serial number is <code><type>-<consolePort></code>. - Here's an example serial number: <code>emulator-5554</code></li> - <li>State — The connection state of the instance may be one of the following: - <ul> - <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> - <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not - imply that the Android system is fully booted and operational, since the instance connects to adb - while the system is still booting. However, after boot-up, this is the normal operational state of - an emulator/device instance.</li> - <li><code>no device</code> — there is no emulator/device connected. - </ul> - </li> + <li>Serial number — A string created by adb to uniquely identify an emulator/device instance by its + console port number. The format of the serial number is <code><type>-<consolePort></code>. + Here's an example serial number: <code>emulator-5554</code></li> + <li>State — The connection state of the instance may be one of the following: + <ul> + <li><code>offline</code> — the instance is not connected to adb or is not responding.</li> + <li><code>device</code> — the instance is now connected to the adb server. Note that this state does not + imply that the Android system is fully booted and operational, since the instance connects to adb + while the system is still booting. However, after boot-up, this is the normal operational state of + an emulator/device instance.</li> + <li><code>no device</code> — there is no emulator/device connected. + </ul> + </li> </ul> <p>The output for each instance is formatted like this: </p> - <pre class="no-pretty-print">[serialNumber] [state]</pre> + <pre class="no-pretty-print">[serialNumber] [state]</pre> <p>Here's an example showing the <code>devices</code> command and its output:</p> - <pre class="no-pretty-print">adb devices -List of devices attached + <pre class="no-pretty-print">adb devices +List of devices attached emulator-5554 device emulator-5556 device emulator-5558 device</pre> @@ -323,13 +324,13 @@ emulator-5558 device</pre> when issuing adb commands. To do so, use the <code>-s</code> option in the commands. The usage for the <code>-s</code> option is:</p> - <pre class="no-pretty-print">adb -s <serialNumber> <command> </pre> - +<pre class="no-pretty-print">adb -s <serialNumber> <command> </pre> + <p>As shown, you specify the target instance for a command using its adb-assigned serial number. You can use the <code>devices</code> command to obtain the serial numbers of running emulator/device instances. For example: </p> - <pre class="no-pretty-print">adb -s emulator-5556 install helloWorld.apk</pre> +<pre class="no-pretty-print">adb -s emulator-5556 install helloWorld.apk</pre> <p>Note that, if you issue a command without specifying a target emulator/device instance while multiple devices are available, adb generates an error. @@ -377,10 +378,10 @@ commands let you copy arbitrary directories and files to any location in an emulator/device instance. </p> <p>To copy a file or directory (and its sub-directories) <em>from</em> the emulator or device, use</p> -<pre class="no-pretty-print">adb pull <remote> <local></pre> +<pre class="no-pretty-print">adb pull <remote> <local></pre> <p>To copy a file or directory (and its sub-directories) <em>to</em> the emulator or device, use</p> - <pre class="no-pretty-print">adb push <local> <remote></pre> + <pre class="no-pretty-print">adb push <local> <remote></pre> <p>In the commands, <code><local></code> and <code><remote></code> refer to the paths to the target files/directory on your development machine (local) and on the @@ -397,8 +398,8 @@ emulator/device instance (remote). For example: </p> <h2 id="shellcommands">Issuing Shell Commands</h2> -<p>Adb provides a Unix shell that you can use to run a variety of commands on an emulator -or connected device. The command binaries are stored in the file system of the emulator or device, +<p>Adb provides a Unix shell that you can use to run a variety of commands on an emulator +or connected device. The command binaries are stored in the file system of the emulator or device, at <code>/system/bin/...</code> <p>Two of the most common command tools are <a href="#am">activity manager</a> ({@code am}) and @@ -408,11 +409,11 @@ at <code>/system/bin/...</code> the adb remote shell on the emulator/device. To issue a single command without entering a remote shell, use the <code>shell</code> command like this: </p> - <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell <shell_command></pre> - + <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell <shell_command></pre> + <p>Or enter a remote shell on an emulator/device like this:</p> - <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell</pre> + <pre class="no-pretty-print">adb [-d|-e|-s <serialNumber>] shell</pre> <p>When you are ready to exit the remote shell, press CTRL+D or type <code>exit</code>. </p> @@ -441,8 +442,8 @@ adb shell am start -a android.intent.action.VIEW <p class="table-caption"><strong>Table 2.</strong> Available activity manager commands</p> <table> <tr> - <th>Command</th> - <th>Description</th> + <th>Command</th> + <th>Description</th> </tr> <tr> @@ -641,7 +642,7 @@ screen resolution using a device with a large screen, and vice versa. <td><code> display-density <dpi> </code></td> -<td>Override emulator/device display density. +<td>Override emulator/device display density. This command is helpful for testing your app across different screen densities on high-density screen environment using a low density screen, and vice versa. <p>Example:<br><code>am display-density 480</code> @@ -662,7 +663,7 @@ to-uri <INTENT> to-intent-uri <INTENT> </code></td> <td>Print the given intent specification as an {@code intent:} URI. <p>See the -<a href="#IntentSpec">Specification for <INTENT> arguments</a>. +<a href="#IntentSpec">Specification for <INTENT> arguments</a>. </td> </tr> </table> @@ -688,7 +689,7 @@ specify the intent with the following options:</p> <dt>{@code -d <DATA_URI>}</dt> <dd>Specify the intent data URI, such as "content://contacts/people/1". You can declare this only once. - + <dt>{@code -t <MIME_TYPE>}</dt> <dd>Specify the intent MIME type, such as "image/png". You can declare this only once. @@ -843,8 +844,8 @@ adb shell pm uninstall com.example.MyApp <p class="table-caption"><strong>Table 3.</strong> Available package manager commands.</p> <table> <tr> - <th>Command</th> - <th>Description</th> + <th>Command</th> + <th>Description</th> </tr> <tr> @@ -1097,12 +1098,12 @@ get-max-users <h3 id="sqlite">Examining sqlite3 databases from a remote shell</h3> -<p>From an adb remote shell, you can use the -<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to -manage SQLite databases created by Android applications. The -<code>sqlite3</code> tool includes many useful commands, such as -<code>.dump</code> to print out the contents of a table and -<code>.schema</code> to print the SQL CREATE statement for an existing table. +<p>From an adb remote shell, you can use the +<a href="http://www.sqlite.org/sqlite.html">sqlite3</a> command-line program to +manage SQLite databases created by Android applications. The +<code>sqlite3</code> tool includes many useful commands, such as +<code>.dump</code> to print out the contents of a table and +<code>.schema</code> to print the SQL CREATE statement for an existing table. The tool also gives you the ability to execute SQLite commands on the fly.</p> <p>To use <code>sqlite3</code>, enter a remote shell on the emulator instance, as described above, then invoke the tool using the <code>sqlite3</code> command. Optionally, when invoking <code>sqlite3</code> you can specify the full path to the database you want to explore. Emulator/device instances store SQLite3 databases in the folder <code><span chatdir="1"><span chatindex="259474B4B070F261">/data/data/<em><package_name></em>/databases</span></span>/</code>. </p> @@ -1126,7 +1127,7 @@ sqlite> .exit </pre> <h3 id="monkey">UI/Application Exerciser Monkey</h3> <p>The Monkey is a program that runs on your emulator or device and generates pseudo-random -streams of user events such as clicks, touches, or gestures, as well as a number of system-level +streams of user events such as clicks, touches, or gestures, as well as a number of system-level events. You can use the Monkey to stress-test applications that you are developing, in a random yet repeatable manner.</p> @@ -1135,7 +1136,7 @@ application and sends 500 pseudo-random events to it.</p> <pre class="no-pretty-print">adb shell monkey -v -p your.package.name 500</pre> -<p>For more information about command options for Monkey, see the complete +<p>For more information about command options for Monkey, see the complete <a href="{@docRoot}tools/help/monkey.html" title="monkey">UI/Application Exerciser Monkey</a> documentation page.</p> @@ -1155,15 +1156,15 @@ application and sends 500 pseudo-random events to it.</p> <p class="table-caption"><strong>Table 4.</strong> Some other adb shell commands</p> <table> <tr> - <th>Shell Command</th> - <th>Description</th> - <th>Comments</th> + <th>Shell Command</th> + <th>Description</th> + <th>Comments</th> </tr> <tr> <td><code>dumpsys</code></td> <td>Dumps system data to the screen.</td> -<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a> +<td rowspan=4">The <a href="{@docRoot}tools/debugging/ddms.html">Dalvik Debug Monitor Server</a> (DDMS) tool offers integrated debug environment that you may find easier to use.</td> </tr> diff --git a/docs/html/tools/help/adt.jd b/docs/html/tools/help/adt.jd index 18e7443..4dac574 100644 --- a/docs/html/tools/help/adt.jd +++ b/docs/html/tools/help/adt.jd @@ -1,4 +1,5 @@ page.title=Android Developer Tools +page.tags="adt" @jd:body <div id="qv-wrapper"> diff --git a/docs/html/tools/samples/index.jd b/docs/html/tools/samples/index.jd index ed416e6..76ba37a 100644 --- a/docs/html/tools/samples/index.jd +++ b/docs/html/tools/samples/index.jd @@ -1,5 +1,5 @@ page.title=Samples - +page.tags="example","code" @jd:body <p>To help you understand some fundamental Android APIs and coding practices, a variety of sample diff --git a/docs/html/tools/sdk/installing.jd b/docs/html/tools/sdk/installing.jd index d7f1957..19e8990 100644 --- a/docs/html/tools/sdk/installing.jd +++ b/docs/html/tools/sdk/installing.jd @@ -1,4 +1,5 @@ page.title=Installing the SDK +excludeFromSuggestions=true @jd:body diff --git a/docs/html/training/camera/index.jd b/docs/html/training/camera/index.jd index fa754a0..d6305d6 100644 --- a/docs/html/training/camera/index.jd +++ b/docs/html/training/camera/index.jd @@ -1,5 +1,5 @@ page.title=Capturing Photos -page.tags="camera","video" +page.tags="camera","video","picture" trainingnavtop=true startpage=true @@ -42,7 +42,7 @@ prevalent. Remember Gopher? We don't, either. For your app to become part of your users' lives, give them a way to put their lives into it. Using the on-board cameras, your application can enable users to augment what they see around them, make unique avatars, look for zombies around the corner, -or simply share their experiences.</p> +or simply share their experiences.</p> <p>This class gets you clicking fast with some super-easy ways of leveraging existing camera applications. In later lessons, you dive deeper @@ -50,7 +50,7 @@ and learn how to control the camera hardware directly.</p> <h2>Lessons</h2> - + <dl> <dt><b><a href="photobasics.html">Taking Photos Simply</a></b></dt> <dd>Leverage other applications and capture photos with just a few lines of code.</dd> @@ -58,5 +58,5 @@ and learn how to control the camera hardware directly.</p> <dd>Leverage other applications and record videos with just a few lines of code.</dd> <dt><b><a href="cameradirect.html">Controlling the Camera</a></b></dt> <dd>Control the camera hardware directly and implement your own camera application.</dd> -</dl> +</dl> diff --git a/docs/html/training/implementing-navigation/ancestral.jd b/docs/html/training/implementing-navigation/ancestral.jd index ac35e64..4e0b742 100644 --- a/docs/html/training/implementing-navigation/ancestral.jd +++ b/docs/html/training/implementing-navigation/ancestral.jd @@ -1,12 +1,6 @@ -page.title=Implementing Ancestral Navigation -parent.title=Implementing Effective Navigation -parent.link=index.html +page.title=Providing Up Navigation trainingnavtop=true -previous.title=Implementing Lateral Navigation -previous.link=lateral.html -next.title=Implementing Temporal Navigation -next.link=temporal.html @jd:body @@ -15,8 +9,9 @@ next.link=temporal.html <h2>This lesson teaches you to:</h2> <ol> - <li><a href="#up">Implement <em>Up</em> Navigation</a></li> - <li><a href="#app-home">Properly Handle the Application Home Screen</a></li> + <li><a href="#SpecifyParent">Specify the Parent Activity</a></li> + <li><a href="#up">Add Up Action</a></li> + <li><a href="#NavigateUp">Navigate Up to Parent Activity</a></li> </ol> <h2>You should also read</h2> @@ -38,87 +33,180 @@ next.link=temporal.html </div> -<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> +<p>All screens in your app that are not the main entrance to your app (the "home" screen) +should offer the user a way to navigate to the logical parent screen in the app's hierarchy by +pressing the <em>Up</em> button in the <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>. +This lesson shows you how to properly implement this behavior.</p> + +<div class="note design"> +<p><strong>Up Navigation Design</strong></p> +<p>The concepts and principles for <em>Up</em> navigation are described in <a +href="{@docRoot}training/design-navigation/ancestral-temporal.html">Designing Effective +Navigation</a> and the <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> design +guide.</p> +</div> -<h2 id="up">Implement <em>Up</em> Navigation</h2> +<img src="{@docRoot}images/training/implementing-navigation-up.png" id="figure-up"> +<p class="img-caption"><strong>Figure 1.</strong> The <em>Up</em> button in the action bar.</p> -<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> -<img src="{@docRoot}images/training/implementing-navigation-up.png" - alt="The Up button in the action bar." id="figure-up"> +<h2 id="SpecifyParent">Specify the Parent Activity</h2> -<p class="img-caption"><strong>Figure 1.</strong> The <em>Up</em> button in the action bar.</p> +<p>To implement <em>Up</em> navigation, the first step is to declare which activity is the +appropriate parent for each activity. Doing so allows the system to facilitate navigation patterns +such as <em>Up</em> because the system can determine the logical parent activity from +the manifest file.</p> + +<p>Beginning in Android 4.1 (API level 16), you can declare the logical parent of each +activity by specifying the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute +in the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code <activity>}</a> +element.</p> + +<p>If your app supports Android 4.0 and lower, include the +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> with your app and +add a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> +element inside the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>. Then specify the parent activity as the value +for {@code android.support.PARENT_ACTIVITY}, matching the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute.</p> + +<p>For example:</p> -<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> +<pre> +<application ... > + ... + <!-- The main/home activity (it has no parent activity) --> + <activity + android:name="com.example.myfirstapp.MainActivity" ...> + ... + </activity> + <!-- A child of the main activity --> + <activity + android:name="com.example.myfirstapp.DisplayMessageActivity" + android:label="@string/title_activity_display_message" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + <!-- Parent activity meta-data to support 4.0 and lower --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.myfirstapp.MainActivity" /> + </activity> +</application> +</pre> + +<p>With the parent activity declared this way, you can navigate <em>Up</em> +to the appropriate parent using the {@link android.support.v4.app.NavUtils} APIs, as shown in +the following sections.</p> -<p>To implement <em>Up</em>, enable it in the action bar in your activity's {@link android.app.Activity#onCreate onCreate()} method:</p> + +<h2 id="up">Add Up Action</h2> + +<p>To allow <em>Up</em> navigation with the app icon in the action bar, call +{@link android.app.ActionBar#setDisplayHomeAsUpEnabled setDisplayHomeAsUpEnabled()}:</p> <pre> {@literal @}Override public void onCreate(Bundle savedInstanceState) { ... getActionBar().setDisplayHomeAsUpEnabled(true); - ... } </pre> -<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> +<p>This adds a left-facing caret alongside the app icon and enables it as an action button +such that when the user presses it, your activity receives a call to +{@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()}. The +ID for the action is {@code android.R.id.home}.</p> + + + +<h2 id="NavigateUp">Navigate Up to Parent Activity</h2> + +<p>To navigate up when the user presses the app icon, you can use the {@link +android.support.v4.app.NavUtils} class's static method, +{@link android.support.v4.app.NavUtils#navigateUpFromSameTask +navigateUpFromSameTask()}. When you call this method, it finishes the current activity and +starts (or resumes) the appropriate parent activity. +If the target parent activity is in the task's back stack, it is brought +forward as defined by {@link android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP}.</p> + +<p>For example:</p> <pre> {@literal @}Override public boolean onOptionsItemSelected(MenuItem item) { switch (item.getItemId()) { - case android.R.id.home: - // This is called when the Home (Up) button is pressed - // in the Action Bar. - Intent parentActivityIntent = new Intent(this, MyParentActivity.class); - parentActivityIntent.addFlags( - Intent.FLAG_ACTIVITY_CLEAR_TOP | - Intent.FLAG_ACTIVITY_NEW_TASK); - startActivity(parentActivityIntent); - finish(); - return true; + // Respond to the action bar's Up/Home button + case android.R.id.home: + NavUtils.navigateUpFromSameTask(this); + return true; } return super.onOptionsItemSelected(item); } </pre> -<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> +<p>However, using {@link android.support.v4.app.NavUtils#navigateUpFromSameTask +navigateUpFromSameTask()} is suitable <strong>only when your app is the owner of the current +task</strong> (that is, the user began this task from your app). If that's not true and your +activity was started in a task that belongs to a different app, then +navigating <em>Up</em> should create a new task that belongs to your app, which +requires that you create a new back stack.</p> + + +<h3 id="BuildBackStack">Navigate up with a new back stack</h3> -<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> +<p>If your activity provides any <a +href="{@docRoot}guide/components/intents-filters.html#ifs">intent filters</a> +that allow other apps to start the +activity, you should implement the {@link android.app.Activity#onOptionsItemSelected +onOptionsItemSelected()} callback such that if the user presses the <em>Up</em> button +after entering your activity from another app's task, your app starts a new task +with the appropriate back stack before navigating up.</p> + +<p>You can do so by first calling +{@link android.support.v4.app.NavUtils#shouldUpRecreateTask shouldUpRecreateTask()} to check +whether the current activity instance exists in a different app's task. If +it returns true, then build a new task with {@link android.support.v4.app.TaskStackBuilder}. +Otherwise, you can use the {@link android.support.v4.app.NavUtils#navigateUpFromSameTask +navigateUpFromSameTask()} method as shown above.</p> + +<p>For example:</p> <pre> {@literal @}Override public boolean onOptionsItemSelected(MenuItem item) { switch (item.getItemId()) { - case android.R.id.home: - Intent upIntent = new Intent(this, MyParentActivity.class); - if (NavUtils.shouldUpRecreateTask(this, upIntent)) { - // This activity is not part of the application's task, so create a new task - // with a synthesized back stack. - TaskStackBuilder.from(this) - .addNextIntent(new Intent(this, MyGreatGrandParentActivity.class)) - .addNextIntent(new Intent(this, MyGrandParentActivity.class)) - .addNextIntent(upIntent) - .startActivities(); - finish(); - } else { - // This activity is part of the application's task, so simply - // navigate up to the hierarchical parent activity. - NavUtils.navigateUpTo(this, upIntent); - } - return true; + // Respond to the action bar's Up/Home button + case android.R.id.home: + Intent upIntent = NavUtils.getParentActivityIntent(this); + if (NavUtils.shouldUpRecreateTask(this, upIntent)) { + // This activity is NOT part of this app's task, so create a new task + // when navigating up, with a synthesized back stack. + TaskStackBuilder.create(this) + // Add all of this activity's parents to the back stack + .addNextIntentWithParentStack(upIntent) + // Navigate up to the closest parent + .startActivities(); + } else { + // This activity is part of this app's task, so simply + // navigate up to the logical parent activity. + NavUtils.navigateUpTo(this, upIntent); + } + return true; } return super.onOptionsItemSelected(item); } </pre> -<h2 id="app-home">Properly Handle the Application Home Screen</h2> - -<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> - -<pre> -getActionBar().setHomeButtonEnabled(false); -</pre> +<p class="note"><strong>Note:</strong> In order for the {@link +android.support.v4.app.TaskStackBuilder#addNextIntentWithParentStack addNextIntentWithParentStack()} +method to work, +you must declare the logical parent of each activity in your manifest file, using the +<a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute (and corresponding <a +href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> element) +as described above.</p> diff --git a/docs/html/training/implementing-navigation/index.jd b/docs/html/training/implementing-navigation/index.jd index 990bcfe..3577170 100644 --- a/docs/html/training/implementing-navigation/index.jd +++ b/docs/html/training/implementing-navigation/index.jd @@ -1,5 +1,5 @@ page.title=Implementing Effective Navigation -page.tags="viewpager","tasks","back","up" +page.tags="viewpager","tasks","back","up","swipe view","DrawerLayout" trainingnavtop=true startpage=true @@ -12,9 +12,9 @@ startpage=true <h2>Dependencies and prerequisites</h2> <ul> - <li>API level 14</li> + <li>Android 2.2 or higher</li> <li>Understanding of fragments and Android layouts</li> - <li><a href="{@docRoot}tools/extras/support-library.html">The Android Support Package</a></li> + <li><a href="{@docRoot}tools/extras/support-library.html">Android Support Library</a></li> <li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a></li> </ul> @@ -40,28 +40,38 @@ startpage=true <p>This class demonstrates how to implement the key navigation design patterns detailed in the <a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a> class. -The lessons in this class cover implementing navigation up, down, and across your application's <a -href="{@docRoot}training/design-navigation/screen-planning.html#diagram- relationships">screen -map</a>.</p> +</p> -<p>After reading through the lessons in this class and exploring the associated sample application -(see right), you should also have a basic understanding of how to use -{@link android.app.ActionBar} and {@link android.support.v4.view.ViewPager}, two components that are fundamental to core app navigation.</p> +<p>After reading the lessons in this class, you should have a strong understanding of how to +implement navigation patterns with tabs, swipe views, and a navigation drawer. You should also +understand how to provide proper <em>Up</em> and <em>Back</em> navigation.</p> +<p class="note"><strong>Note:</strong> Several elements of this class require the +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> APIs. +If you have not used the Support Library before, follow the lesson about <a +href="{@docRoot}training/basics/fragments/support-lib.html">Using the Support Library</a> +to get your project set up.</p> -<h2 id="lessons">Lessons</h2> +<h2 id="lessons">Lessons</h2> <dl> - <dt><strong><a href="lateral.html">Implementing Lateral Navigation</a></strong></dt> - <dd>Learn how to implement tabs and horizontal paging (swipe views).</dd> + <dt><strong><a href="lateral.html">Creating Swipe Views with Tabs</a></strong></dt> + <dd>Learn how to implement tabs in the action bar and provide + horizontal paging (swipe views) to navigate between tabs.</dd> + + <dt><strong><a href="nav-drawer.html">Creating a Navigation Drawer</a></strong></dt> + <dd>Learn how to build an interface with a hidden navigation drawer on the side + of the screen that opens with a swipe or by pressing the action bar's app icon.</dd> - <dt><strong><a href="ancestral.html">Implementing Ancestral Navigation</a></strong></dt> - <dd>Learn how to implement <em>Up</em> navigation.</dd> + <dt><strong><a href="ancestral.html">Providing Up Navigation</a></strong></dt> + <dd>Learn how to implement <em>Up</em> navigation using the action bar's app icon.</dd> - <dt><strong><a href="temporal.html">Implementing Temporal Navigation</a></strong></dt> - <dd>Learn how to correctly handle the <em>Back</em> button.</dd> + <dt><strong><a href="temporal.html">Providing Proper Back Navigation</a></strong></dt> + <dd>Learn how to correctly handle the <em>Back</em> button in special cases, + including how to insert activities into the back stack when deep-linking the user + from notifications or app widgets.</dd> <dt><strong><a href="descendant.html">Implementing Descendant Navigation</a></strong></dt> - <dd>Learn the finer points of implementing navigation into your application's information hierarchy.</dd> + <dd>Learn the finer points of navigating down into your application's information hierarchy.</dd> </dl> diff --git a/docs/html/training/implementing-navigation/lateral.jd b/docs/html/training/implementing-navigation/lateral.jd index c8f57a2..4ab8fbd 100644 --- a/docs/html/training/implementing-navigation/lateral.jd +++ b/docs/html/training/implementing-navigation/lateral.jd @@ -1,10 +1,6 @@ -page.title=Implementing Lateral Navigation -parent.title=Implementing Effective Navigation -parent.link=index.html +page.title=Creating Swipe Views with Tabs trainingnavtop=true -next.title=Implementing Ancestral Navigation -next.link=ancestral.html @jd:body @@ -13,11 +9,13 @@ next.link=ancestral.html <h2>This lesson teaches you to</h2> <ol> - <li><a href="#tabs">Implement Tabs</a></li> - <li><a href="#horizontal-paging">Implement Horizontal Paging (Swipe Views)</a></li> - <li><a href="#swipe-tabs">Implement Swiping Between Tabs</a></li> + <li><a href="#horizontal-paging">Implement Swipe Views</a></li> + <li><a href="#tabs">Add Tabs to the Action Bar</a></li> + <li><a href="#swipe-tabs">Change Tabs with Swipe Views</a></li> + <li><a href="#PagerTitleStrip">Use a Title Strip Instead of Tabs</a></li> </ol> + <h2>You should also read</h2> <ul> <li><a href="{@docRoot}training/design-navigation/descendant-lateral.html">Providing Descendant and Lateral Navigation</a></li> @@ -37,92 +35,60 @@ next.link=ancestral.html </div> -<p><em>Lateral navigation</em> is navigation between sibling screens in the application's screen hierarchy (sometimes referred to as a screen map). The most prominent lateral navigation patterns are tabs and horizontal paging (also known as swipe views). This pattern and others are described in <a href="{@docRoot}training/design-navigation/descendant-lateral.html">Designing Effective Navigation</a>. This lesson covers how to implement several of the primary lateral navigation patterns in Android.</p> +<p>Swipe views provide lateral navigation between sibling screens such as tabs with +a horizontal finger gesture (a pattern sometimes known as horizontal paging). This lesson teaches +you how to create a tab layout with swipe views for switching between tabs, or how to show +a title strip instead of tabs.</p> -<h2 id="tabs">Implement Tabs</h2> +<div class="note design"> +<p><strong>Swipe View Design</strong></p> +<p>Before implementing these features, you should understand the concepts and recommendations +as described in <a href="{@docRoot}training/design-navigation/descendant-lateral.html">Designing +Effective Navigation</a> and the <a href="{@docRoot}design/patterns/swipe-views.html">Swipe +Views</a> design guide.</p> +</div> -<p>Tabs allow the user to navigate between sibling screens by selecting the appropriate tab indicator available at the top of the display. In Android 3.0 and later, tabs are implemented using the {@link android.app.ActionBar} class, and are generally set up in {@link android.app.Activity#onCreate Activity.onCreate()}. In some cases, such as when horizontal space is limited and/or the number of tabs is large, an appropriate alternate presentation for tabs is a dropdown list (sometimes implemented using a {@link android.widget.Spinner}).</p> -<p>In previous versions of Android, tabs could be implemented using a -{@link android.widget.TabWidget} and {@link android.widget.TabHost}.</p> -<p>As of Android 3.0, however, you should use either {@link android.app.ActionBar#NAVIGATION_MODE_TABS} or {@link android.app.ActionBar#NAVIGATION_MODE_LIST} along with the {@link android.app.ActionBar} class.</p> -<h3>Implement the Tabs Pattern with NAVIGATION_MODE_TABS</h3> -<p>To create tabs, you can use the following code in your activity's {@link android.app.Activity#onCreate onCreate()} method. Note that the exact presentation of tabs may vary per device and by the current device configuration, to make best use of available screen space. For example, Android may automatically collapse tabs into a dropdown list if tabs don't fit horizontally in the action bar.</p> +<h2 id="horizontal-paging">Implement Swipe Views</h2> -<pre> -{@literal @}Override -public void onCreate(Bundle savedInstanceState) { - ... - final ActionBar actionBar = getActionBar(); +<p>You can create swipe views in your app using the {@link android.support.v4.view.ViewPager} +widget, available in the +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>. The +{@link android.support.v4.view.ViewPager} is a layout widget in which each child view is +a separate page (a separate tab) in the layout.</p> - // Specify that tabs should be displayed in the action bar. - actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); - - // Create a tab listener that is called when the user changes tabs. - ActionBar.TabListener tabListener = new ActionBar.TabListener() { - public void onTabSelected(ActionBar.Tab tab, - FragmentTransaction ft) { } - - public void onTabUnselected(ActionBar.Tab tab, - FragmentTransaction ft) { } - - public void onTabReselected(ActionBar.Tab tab, - FragmentTransaction ft) { } - }; - - // Add 3 tabs. - for (int i = 0; i < 3; i++) { - actionBar.addTab( - actionBar.newTab() - .setText("Tab " + (i + 1)) - .setTabListener(tabListener)); - } - ... -} -</pre> - -<h3>Implement the Tabs Pattern with NAVIGATION_MODE_LIST</h3> - -<p>To use a dropdown list instead, use the following code in your activity's {@link android.app.Activity#onCreate onCreate()} method. Dropdown lists are often preferable in cases where more information must be shown per navigation item, such as unread message counts, or where the number of available navigation items is large.</p> +<p>To set up your layout with {@link android.support.v4.view.ViewPager}, add a +{@code <ViewPager>} element to your XML layout. For example, if each page in the swipe view +should consume the entire layout, then your layout looks like this:</p> <pre> -{@literal @}Override -public void onCreate(Bundle savedInstanceState) { - ... - final ActionBar actionBar = getActionBar(); - - // Specify that a dropdown list should be displayed in the action bar. - actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_LIST); - - actionBar.setListNavigationCallbacks( - // Specify a SpinnerAdapter to populate the dropdown list. - new ArrayAdapter<String>( - actionBar.getThemedContext(), - android.R.layout.simple_list_item_1, - android.R.id.text1, - new String[]{ "Tab 1", "Tab 2", "Tab 3" }), - - // Provide a listener to be called when an item is selected. - new ActionBar.OnNavigationListener() { - public boolean onNavigationItemSelected( - int position, long id) { - // Take action here, e.g. switching to the - // corresponding fragment. - return true; - } - }); - ... -} +<?xml version="1.0" encoding="utf-8"?> +<android.support.v4.view.ViewPager + xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/pager" + android:layout_width="match_parent" + android:layout_height="match_parent" /> </pre> -<h2 id="horizontal-paging">Implement Horizontal Paging (Swipe Views)</h2> +<p>To insert child views that represent each page, +you need to hook this layout to a {@link android.support.v4.view.PagerAdapter}. +There are two kinds of adapter you can use:</p> -<p>Horizontal paging, or swipe views, allow users to <a href="{@docRoot}design/patterns/swipe-views.html">swipe</a> horizontally on the current screen to navigate to adjacent screens. This pattern can be implemented using the {@link android.support.v4.view.ViewPager} widget, currently available as part of the <a href="{@docRoot}tools/extras/support-library.html">Android Support Package</a>. For navigating between sibling screens representing a fixed number of sections, it's best to provide the {@link android.support.v4.view.ViewPager} with a {@link android.support.v4.app.FragmentPagerAdapter}. For horizontal paging across collections of objects, it's best to use a {@link android.support.v4.app.FragmentStatePagerAdapter}, which destroys fragments as the user navigates to other pages, minimizing memory usage.</p> +<dl> + <dt>{@link android.support.v4.app.FragmentPagerAdapter}</dt> + <dd>This is best when navigating between sibling screens representing a fixed, small + number of pages.</dd> + <dt>{@link android.support.v4.app.FragmentStatePagerAdapter}</dt> + <dd>This is best for paging across a collection of objects +for which the number of pages is undetermined. It destroys +fragments as the user navigates to other pages, minimizing memory usage.</dd> +</dl> -<p>Below is an example of using a {@link android.support.v4.view.ViewPager} to swipe across a collection of objects.</p> +<p>For example, here's how you might use {@link android.support.v4.app.FragmentStatePagerAdapter} +to swipe across a collection of {@link android.app.Fragment} objects:</p> <pre> public class CollectionDemoActivity extends FragmentActivity { @@ -147,8 +113,7 @@ public class CollectionDemoActivity extends FragmentActivity { // Since this is an object collection, use a FragmentStatePagerAdapter, // and NOT a FragmentPagerAdapter. -public class DemoCollectionPagerAdapter extends - FragmentStatePagerAdapter { +public class DemoCollectionPagerAdapter extends FragmentStatePagerAdapter { public DemoCollectionPagerAdapter(FragmentManager fm) { super(fm); } @@ -194,38 +159,99 @@ public static class DemoObjectFragment extends Fragment { } </pre> -<p>You can also add indicators to your horizontal paging UI by adding a {@link android.support.v4.view.PagerTitleStrip}. Below is an example layout XML file for an activity whose entire contents are a {@link android.support.v4.view.ViewPager} and a top-aligned {@link android.support.v4.view.PagerTitleStrip} inside it. Individual pages (provided by the adapter) occupy the remaining space inside the {@link android.support.v4.view.ViewPager}.</p> +<p>This example shows only the code necessary to create the swipe views. The following +sections show how you can add tabs to help facilitate navigation between pages.</p> + + +<h2 id="tabs">Add Tabs to the Action Bar</h2> + +<p>Action bar +<a href="{@docRoot}design/building-blocks/tabs.html">tabs</a> offer users a familiar interface +for navigating between and identifying sibling screens in your app.</p> + +<p>To create tabs using {@link android.app.ActionBar}, you need to enable +{@link android.app.ActionBar#NAVIGATION_MODE_TABS}, then create several instances of +{@link android.app.ActionBar.Tab} and supply an implementation of +the {@link android.app.ActionBar.TabListener} interface for each one. +For example, in your activity's {@link +android.app.Activity#onCreate onCreate()} method, you can use code similar to this:</p> <pre> -<android.support.v4.view.ViewPager - xmlns:android="http://schemas.android.com/apk/res/android" - android:id="@+id/pager" - android:layout_width="match_parent" - android:layout_height="match_parent"> +{@literal @}Override +public void onCreate(Bundle savedInstanceState) { + final ActionBar actionBar = getActionBar(); + ... - <android.support.v4.view.PagerTitleStrip - android:id="@+id/pager_title_strip" - android:layout_width="match_parent" - android:layout_height="wrap_content" - android:layout_gravity="top" - android:background="#33b5e5" - android:textColor="#fff" - android:paddingTop="4dp" - android:paddingBottom="4dp" /> + // Specify that tabs should be displayed in the action bar. + actionBar.setNavigationMode(ActionBar.NAVIGATION_MODE_TABS); -</android.support.v4.view.ViewPager> + // Create a tab listener that is called when the user changes tabs. + ActionBar.TabListener tabListener = new ActionBar.TabListener() { + public void onTabSelected(ActionBar.Tab tab, FragmentTransaction ft) { + // show the given tab + } + + public void onTabUnselected(ActionBar.Tab tab, FragmentTransaction ft) { + // hide the given tab + } + + public void onTabReselected(ActionBar.Tab tab, FragmentTransaction ft) { + // probably ignore this event + } + }; + + // Add 3 tabs, specifying the tab's text and TabListener + for (int i = 0; i < 3; i++) { + actionBar.addTab( + actionBar.newTab() + .setText("Tab " + (i + 1)) + .setTabListener(tabListener)); + } +} </pre> -<h2 id="swipe-tabs">Implement Swiping Between Tabs</h2> +<p>How you handle the {@link android.app.ActionBar.TabListener} callbacks to change tabs +depends on how you've constructed your content. But if you're using fragments for each tab with +{@link android.support.v4.view.ViewPager} as shown above, the following +section shows how to switch between pages when the user selects a tab and also update the selected +tab when the user swipes between pages.</p> + + +<h2 id="swipe-tabs">Change Tabs with Swipe Views</h2> -<p>One of the key design recommendations in Android 4.0 for tabs is to <a href="{@docRoot}design/patterns/swipe-views.html">allow swiping</a> between them where appropriate. This behavior enables users to swipe horizontally across the selected tab's contents to navigate to adjacent tabs, without needed to directly interact with the tabs themselves. To implement this, you can use a {@link android.support.v4.view.ViewPager} in conjunction with the {@link android.app.ActionBar} tabs API.</p> +<p>To switch between pages in a {@link android.support.v4.view.ViewPager} when the user selects +a tab, implement your {@link android.app.ActionBar.TabListener} to select the appropriate page +by calling {@link android.support.v4.view.ViewPager#setCurrentItem setCurrentItem()} on your +{@link android.support.v4.view.ViewPager}:</p> + +<pre> +{@literal @}Override +public void onCreate(Bundle savedInstanceState) { + ... + + // Create a tab listener that is called when the user changes tabs. + ActionBar.TabListener tabListener = new ActionBar.TabListener() { + public void onTabSelected(ActionBar.Tab tab, FragmentTransaction ft) { + // When the tab is selected, switch to the + // corresponding page in the ViewPager. + mViewPager.setCurrentItem(tab.getPosition()); + } + ... + }; +} +</pre> -<p>Upon observing the current page changing, select the corresponding tab. You can set up this behavior using an {@link android.support.v4.view.ViewPager.OnPageChangeListener} in your activity's {@link android.app.Activity#onCreate onCreate()} method:</p> +<p>Likewise, you should select the corresponding tab when the user swipes between pages with a +touch gesture. You can set up this behavior by implementing the +{@link android.support.v4.view.ViewPager.OnPageChangeListener} interface to change +the current tab each time the page changes. For example:</p> <pre> {@literal @}Override public void onCreate(Bundle savedInstanceState) { ... + + mViewPager = (ViewPager) findViewById(R.id.pager); mViewPager.setOnPageChangeListener( new ViewPager.SimpleOnPageChangeListener() { {@literal @}Override @@ -239,18 +265,36 @@ public void onCreate(Bundle savedInstanceState) { } </pre> -<p>And upon selecting a tab, switch to the corresponding page in the {@link android.support.v4.view.ViewPager}. To do this, add an {@link android.app.ActionBar.TabListener} to your tab when creating it using the {@link android.app.ActionBar#newTab newTab()} method:</p> + + +<h2 id="PagerTitleStrip">Use a Title Strip Instead of Tabs</h2> + +<p>If you don't want to include action bar tabs and prefer to provide +<a href="{@docRoot}design/building-blocks/tabs.html#scrollable">scrollable tabs</a> for a shorter +visual profile, you can use {@link android.support.v4.view.PagerTitleStrip} with +your swipe views.</p> + +<p>Below is an example layout XML file for an +activity whose entire contents are a {@link android.support.v4.view.ViewPager} and a top-aligned +{@link android.support.v4.view.PagerTitleStrip} inside it. Individual pages (provided by the +adapter) occupy the remaining space inside the {@link android.support.v4.view.ViewPager}.</p> <pre> -actionBar.newTab() - ... - .setTabListener(new ActionBar.TabListener() { - public void onTabSelected(ActionBar.Tab tab, - FragmentTransaction ft) { - // When the tab is selected, switch to the - // corresponding page in the ViewPager. - mViewPager.setCurrentItem(tab.getPosition()); - } - ... - })); -</pre> +<android.support.v4.view.ViewPager + xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/pager" + android:layout_width="match_parent" + android:layout_height="match_parent"> + + <android.support.v4.view.PagerTitleStrip + android:id="@+id/pager_title_strip" + android:layout_width="match_parent" + android:layout_height="wrap_content" + android:layout_gravity="top" + android:background="#33b5e5" + android:textColor="#fff" + android:paddingTop="4dp" + android:paddingBottom="4dp" /> + +</android.support.v4.view.ViewPager> +</pre>
\ No newline at end of file diff --git a/docs/html/training/implementing-navigation/nav-drawer.jd b/docs/html/training/implementing-navigation/nav-drawer.jd new file mode 100644 index 0000000..756e6c4 --- /dev/null +++ b/docs/html/training/implementing-navigation/nav-drawer.jd @@ -0,0 +1,368 @@ +page.title=Creating a Navigation Drawer + +trainingnavtop=true + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to:</h2> +<ol> + <li><a href="#DrawerLayout">Create a Drawer Layout</a></li> + <li><a href="#Init">Initialize the Drawer List</a></li> + <li><a href="#ListItemClicks">Handle Navigation Click Events</a></li> + <li><a href="#OpenClose">Listen for Open and Close Events</a></li> + <li><a href="#ActionBarIcon">Open and Close with the App Icon</a></li> +</ol> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/NavigationDrawer.zip" + class="button">Download the sample app</a> +<p class="filename">NavigationDrawer.zip</p> +</div> + +</div> +</div> + + + +<p>The navigation drawer is a panel that displays the app’s main navigation options +on the left edge of the screen. It is hidden most of the time, but is revealed +when the user swipes a finger from the left edge of the screen or, while at the top level of the +app, the user touches the app icon in the action bar.</p> + +<p>This lesson describes how to implement a navigation drawer using the +{@link android.support.v4.widget.DrawerLayout} APIs available in the +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>.</p> + +<div class="note design"> +<p><strong>Navigation Drawer Design</strong></p> +<p>Before you decide to use a navigation drawer in your app, you should understand the use +cases and design principles defined in the +<a href="{@docRoot}design/patterns/navigation-drawer.html">Navigation Drawer</a> design guide.</p> +</div> + + +<h2 id="DrawerLayout">Create a Drawer Layout</h2> + +<p>To add a navigation drawer, declare your user interface with a +{@link android.support.v4.widget.DrawerLayout} object as the root view of your layout. +Inside the {@link android.support.v4.widget.DrawerLayout}, add one view that contains +the main content for the screen (your primary layout when the drawer is hidden) and another view +that contains the contents of the navigation drawer.</p> + +<p>For example, the following layout uses a {@link +android.support.v4.widget.DrawerLayout} with two child views: a {@link android.widget.FrameLayout} +to contain the main content (populated by a {@link android.app.Fragment} at +runtime), and a {@link android.widget.ListView} for the navigation drawer.</p> + +<pre> +<android.support.v4.widget.DrawerLayout + xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/drawer_layout" + android:layout_width="match_parent" + android:layout_height="match_parent"> + <!-- The main content view --> + <FrameLayout + android:id="@+id/content_frame" + android:layout_width="match_parent" + android:layout_height="match_parent" /> + <!-- The navigation drawer --> + <ListView android:id="@+id/left_drawer" + android:layout_width="240dp" + android:layout_height="match_parent" + android:layout_gravity="start" + android:choiceMode="singleChoice" + android:divider="@android:color/transparent" + android:dividerHeight="0dp" + android:background="#111"/> +</android.support.v4.widget.DrawerLayout> +</pre> + +<p>This layout demonstrates some important layout characteristics:</p> +<ul> + <li>The main content view (the {@link android.widget.FrameLayout} above) + <strong>must be the first child</strong> in the {@link + android.support.v4.widget.DrawerLayout} because the XML order implies z-ordering + and the drawer must be on top of the content.</li> + <li>The main content view is set to match the parent + view's width and height, because it represents the entire UI when the + navigation drawer is hidden.</li> + <li>The drawer view (the {@link android.widget.ListView}) <strong>must specify its horizontal + gravity</strong> with the {@code android:layout_gravity} attribute. To + support right-to-left (RTL) languages, specify the value with {@code "start"} + instead of {@code "left"} (so the drawer appears on the right when the layout is RTL).</p> + </li> + <li>The drawer view specifies its width in {@code dp} units and the height matches the parent + view. The drawer width should be no more than 320dp so the user can always + see a portion of the main content.</li> +</ul> + + + +<h2 id="Init">Initialize the Drawer List</h2> + +<p>In your activity, one of the first things to do is initialize +the navigation drawer's list of items. How you do so depends on the content of your app, but +a navigation drawer often consists of a {@link android.widget.ListView}, so the list +should be populated by an {@link android.widget.Adapter} (such as {@link +android.widget.ArrayAdapter} or {@link android.widget.SimpleCursorAdapter}).</p> + +<p>For example, here's how you can initialize the navigation list with a +<a href="{@docRoot}guide/topics/resources/string-resource.html#StringArray">string array</a>:</p> + +<pre> +public class MainActivity extends Activity { + private String[] mPlanetTitles; + private ListView mDrawerList; + ... + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + + mPlanetTitles = getResources().getStringArray(R.array.planets_array); + mDrawerList = (ListView) findViewById(R.id.left_drawer); + + // Set the adapter for the list view + mDrawerList.setAdapter(new ArrayAdapter<String>(this, + R.layout.drawer_list_item, mPlanetTitles)); + // Set the list's click listener + mDrawerList.setOnItemClickListener(new DrawerItemClickListener()); + + ... + } +} +</pre> + +<p>This code also calls {@link android.widget.ListView#setOnItemClickListener +setOnItemClickListener()} to receive click events in the navigation drawer's list. +The next section shows how to implement this interface +and change the content view when the user selects an item.</p> + + + +<h2 id="ListItemClicks">Handle Navigation Click Events</h2> + +<p>When the user selects an item in the drawer's list, the system calls {@link +android.widget.AdapterView.OnItemClickListener#onItemClick onItemClick()} on the +{@link android.widget.AdapterView.OnItemClickListener OnItemClickListener} given to +{@link android.widget.ListView#setOnItemClickListener setOnItemClickListener()}.</p> + +<p>What you do in the {@link +android.widget.AdapterView.OnItemClickListener#onItemClick onItemClick()} method +depends on how you've implemented your <a +href="{@docRoot}design/patterns/app-structure.html">app structure</a>. In the following example, +selecting each item in the list inserts a different {@link +android.app.Fragment} into the main content view (the +{@link android.widget.FrameLayout} element identified by the {@code R.id.content_frame} ID):</p> + +<pre> +private class DrawerItemClickListener implements ListView.OnItemClickListener { + @Override + public void onItemClick(AdapterView<?> parent, View view, int position, long id) { + selectItem(position); + } +} + +/** Swaps fragments in the main content view */ +private void selectItem(int position) { + // Create a new fragment and specify the planet to show based on position + Fragment fragment = new PlanetFragment(); + Bundle args = new Bundle(); + args.putInt(PlanetFragment.ARG_PLANET_NUMBER, position); + fragment.setArguments(args); + + // Insert the fragment by replacing any existing fragment + FragmentManager fragmentManager = getFragmentManager(); + fragmentManager.beginTransaction() + .replace(R.id.content_frame, fragment) + .commit(); + + // Highlight the selected item, update the title, and close the drawer + mDrawer.setItemChecked(position, true); + setTitle(mPlanetTitles[position]); + mDrawerLayout.closeDrawer(mDrawer); +} + +@Override +public void setTitle(CharSequence title) { + mTitle = title; + getActionBar().setTitle(mTitle); +} + +</pre> + + + + +<h2 id="OpenClose">Listen for Open and Close Events</h2> + +<p>To listen for drawer open and close events, call {@link +android.support.v4.widget.DrawerLayout#setDrawerListener setDrawerListener()} on your +{@link android.support.v4.widget.DrawerLayout} and pass it an implementation of +{@link android.support.v4.widget.DrawerLayout.DrawerListener}. This interface provides callbacks +for drawer events such as {@link +android.support.v4.widget.DrawerLayout.DrawerListener#onDrawerOpened onDrawerOpened()} and {@link +android.support.v4.widget.DrawerLayout.DrawerListener#onDrawerClosed onDrawerClosed()}.</p> + +<p>However, rather than implementing the {@link +android.support.v4.widget.DrawerLayout.DrawerListener}, if your activity includes the +<a href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>, you can instead +extend the {@link android.support.v4.app.ActionBarDrawerToggle} class. The +{@link android.support.v4.app.ActionBarDrawerToggle} implements +{@link android.support.v4.widget.DrawerLayout.DrawerListener} so you can still override those +callbacks, but it also facilitates the proper +interaction behavior between the action bar icon and the navigation drawer (discussed further in +the next section).</p> + +<p>As discussed in the <a href="{@docRoot}design/patterns/navigation-drawer.html">Navigation +Drawer</a> design guide, you should modify the contents of the action bar +when the drawer is visible, such as to change the title and remove action items that are +contextual to the main content. The following code shows how you can do so by overriding {@link +android.support.v4.widget.DrawerLayout.DrawerListener} callback methods with an instance +of the {@link android.support.v4.app.ActionBarDrawerToggle} class:</p> + +<pre> +public class MainActivity extends Activity { + private DrawerLayout mDrawerLayout; + private ActionBarDrawerToggle mDrawerToggle; + private CharSequence mDrawerTitle; + private CharSequence mTitle; + ... + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.activity_main); + ... + + mTitle = mDrawerTitle = getTitle(); + mDrawerLayout = (DrawerLayout) findViewById(R.id.drawer_layout); + mDrawerToggle = new ActionBarDrawerToggle(this, mDrawerLayout, + R.drawable.ic_drawer, R.string.drawer_open, R.string.drawer_close) { + + /** Called when a drawer has settled in a completely closed state. */ + public void onDrawerClosed(View view) { + getActionBar().setTitle(mTitle); + invalidateOptionsMenu(); // creates call to onPrepareOptionsMenu() + } + + /** Called when a drawer has settled in a completely open state. */ + public void onDrawerOpened(View drawerView) { + getActionBar().setTitle(mDrawerTitle); + invalidateOptionsMenu(); // creates call to onPrepareOptionsMenu() + } + }; + + // Set the drawer toggle as the DrawerListener + mDrawerLayout.setDrawerListener(mDrawerToggle); + } + + /* Called whenever we call invalidateOptionsMenu() */ + @Override + public boolean onPrepareOptionsMenu(Menu menu) { + // If the nav drawer is open, hide action items related to the content view + boolean drawerOpen = mDrawerLayout.isDrawerOpen(mDrawerList); + menu.findItem(R.id.action_websearch).setVisible(!drawerOpen); + return super.onPrepareOptionsMenu(menu); + } +} +</pre> + +<p>The next section describes the {@link android.support.v4.app.ActionBarDrawerToggle} constructor +arguments and the other steps required to set it up to handle interaction with the +action bar icon.</p> + + + +<h2 id="ActionBarIcon">Open and Close with the App Icon</h2> + +<p>Users can open and close the navigation drawer with a swipe gesture from or towards the left +edge of the screen, but if you're using the <a +href="{@docRoot}guide/topics/ui/actionbar.html">action bar</a>, you should also allow users to +open and close it by touching the app icon. And the app icon should also indicate the presence of +the navigation drawer with a special icon. You can implement all this behavior by using the +{@link android.support.v4.app.ActionBarDrawerToggle} shown in the previous section.</p> + +<p>To make {@link android.support.v4.app.ActionBarDrawerToggle} work, create an instance of +it with its constructor, which requires the following arguments:</p> +<ul> + <li>The {@link android.app.Activity} hosting the drawer. + <li>The {@link android.support.v4.widget.DrawerLayout}. + <li>A drawable resource to use as the drawer indicator. + <li>A String resource to describe the "open drawer" action (for accessibility). + <li>A String resource to describe the "close drawer" action (for accessibility). +</ul> + +<p>Then, whether or not you've created a subclass of +{@link android.support.v4.app.ActionBarDrawerToggle} as your drawer listener, you need to call +upon your {@link android.support.v4.app.ActionBarDrawerToggle} in a few places throughout your +activity lifecycle:</p> + +<pre> +public class MainActivity extends Activity { + private DrawerLayout mDrawerLayout; + private ActionBarDrawerToggle mDrawerToggle; + ... + + public void onCreate(Bundle savedInstanceState) { + ... + + mDrawerLayout = (DrawerLayout) findViewById(R.id.drawer_layout); + mDrawerToggle = new ActionBarDrawerToggle(this, mDrawerLayout, + R.drawable.ic_drawer, R.string.drawer_open, R.string.drawer_close) { + + /** Called when a drawer has settled in a completely closed state. */ + public void onDrawerClosed(View view) { + getActionBar().setTitle(mTitle); + } + + /** Called when a drawer has settled in a completely open state. */ + public void onDrawerOpened(View drawerView) { + getActionBar().setTitle(mDrawerTitle); + } + }; + + // Set the drawer toggle as the DrawerListener + mDrawerLayout.setDrawerListener(mDrawerToggle); + + getActionBar().setDisplayHomeAsUpEnabled(true); + getActionBar().setHomeButtonEnabled(true); + } + + @Override + protected void onPostCreate(Bundle savedInstanceState) { + super.onPostCreate(savedInstanceState); + // Sync the toggle state after onRestoreInstanceState has occurred. + mDrawerToggle.syncState(); + } + + @Override + public void onConfigurationChanged(Configuration newConfig) { + super.onConfigurationChanged(newConfig); + mDrawerToggle.onConfigurationChanged(newConfig); + } + + @Override + public boolean onOptionsItemSelected(MenuItem item) { + // Pass the event to ActionBarDrawerToggle, if it returns + // true, then it has handled the app icon touch event + if (mDrawerToggle.onOptionsItemSelected(item)) { + return true; + } + // Handle your other action bar items... + + return super.onOptionsItemSelected(item); + } + + ... +} +</pre> + +<p>For a complete example of a navigation drawer, download the sample available at the +<a href="#top">top of the page</a>.</p>
\ No newline at end of file diff --git a/docs/html/training/implementing-navigation/temporal.jd b/docs/html/training/implementing-navigation/temporal.jd index 1c41732..c34a5cf 100644 --- a/docs/html/training/implementing-navigation/temporal.jd +++ b/docs/html/training/implementing-navigation/temporal.jd @@ -1,12 +1,6 @@ -page.title=Implementing Temporal Navigation -parent.title=Implementing Effective Navigation -parent.link=index.html +page.title=Providing Proper Back Navigation trainingnavtop=true -previous.title=Implementing Ancestral Navigation -previous.link=ancestral.html -next.title=Implementing Descendant Navigation -next.link=descendant.html @jd:body @@ -15,8 +9,9 @@ next.link=descendant.html <h2>This lesson teaches you to:</h2> <ol> - <li><a href="#back-fragments">Implement <em>Back</em> Navigation with Fragments</a></li> - <li><a href="#back-webviews">Implement <em>Back</em> Navigation with WebViews</a></li> + <li><a href="#SynthesizeBackStack">Synthesize a new Back Stack for Deep Links</a></li> + <li><a href="#back-fragments">Implement Back Navigation for Fragments</a></li> + <li><a href="#back-webviews">Implement Back Navigation for WebViews</a></li> </ol> <h2>You should also read</h2> @@ -30,32 +25,191 @@ next.link=descendant.html </div> -<p><em>Temporal navigation</em> is navigation to previously visited screens. Users can visit previous screens by pressing the device <em>Back</em> button. This user interface pattern is described further in <a href="{@docRoot}training/design-navigation/ancestral-temporal.html">Providing Ancestral and Temporal Navigation</a> in <em>Designing Effective Navigation</em> and in <a href="{@docRoot}design/patterns/navigation.html">Android Design: Navigation</a>.</p> +<p><em>Back</em> navigation is how users move backward through the history of screens +they previously visited. All Android devices provide a <em>Back</em> button for this +type of navigation, so <strong>your app should not add a Back button to the UI</strong>.</p> -<p>Android handles basic <em>Back</em> navigation for you (see <a href="{@docRoot}guide/components/tasks-and-back-stack.html">Tasks and Back Stack</a> for details on this behavior). This lesson discusses a number of cases where applications should provide specialized logic for the <em>Back</em> button.</p> +<p>In almost all situations, the system maintains a back stack of activities while the user +navigates your application. This allows the system to properly navigate backward when the user +presses the <em>Back</em> button. However, there are a few cases in which your app should manually +specify the <em>Back</em> behavior in order to provide the best user experience.</p> +<div class="note design"> +<p><strong>Back Navigation Design</strong></p> +<p>Before continuing with this document, you should understand the +concepts and principles for <em>Back</em> navigation as described in +the <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> design +guide.</p> +</div> + +<p>Navigation patterns that require you to manually specify the <em>Back</em> behavior include:</p> +<ul> + <li>When the user enters a deep-level activity directly from a <a + href="{@docRoot}guide/topics/ui/notifiers/notifications.html">notification</a>, an <a + href="{@docRoot}guide/topics/appwidgets/index.html">app widget</a>, or the <a + href="{@docRoot}training/implementing-navigation/nav-drawer.html">navigation drawer</a>.</li> + <li>Certain cases in which the user navigates between <a + href="{@docRoot}guide/components/fragments.html">fragments</a>.</li> + <li>When the user navigates web pages in a {@link android.webkit.WebView}.</li> +</ul> + +<p>How to implement proper <em>Back</em> navigation in these situations is described +in the following sections.</p> + + + +<h2 id="SynthesizeBackStack">Synthesize a new Back Stack for Deep Links</h2> + +<p>Ordinarily, the system incrementally builds the back stack as the user navigates from one +activity to the next. However, when the user enters your app with a <em>deep link</em> that +starts the activity in its own task, it's necessary for you to synthesize a new +back stack because the activity is running in a new task without any back stack at all.</p> + +<p>For example, when a notification takes the user to an activity deep in your app hierarchy, +you should add activities into your task's back stack so that pressing <em>Back</em> navigates +up the app hierarchy instead of exiting the app. This pattern is described further in the +<a href="{@docRoot}design/patterns/navigation.html#into-your-app" +>Navigation</a> design guide.</p> + + +<h3 id="SpecifyParent">Specify parent activities in the manifest</h3> + +<p>Beginning in Android 4.1 (API level 16), you can declare the logical parent of each +activity by specifying the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute +in the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a> element. This allows the system to facilitate navigation patterns +because it can determine the logical <em>Back</em> or <em>Up</em> navigation path with this +information.</p> + +<p>If your app supports Android 4.0 and lower, include the +<a href="{@docRoot}tools/extras/support-library.html">Support Library</a> with your app and +add a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> +element inside the <a href="{@docRoot}guide/topics/manifest/activity-element.html">{@code +<activity>}</a>. Then specify the parent activity as the value +for {@code android.support.PARENT_ACTIVITY}, matching the <a +href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute.</p> + +<p>For example:</p> + +<pre> +<application ... > + ... + <!-- The main/home activity (it has no parent activity) --> + <activity + android:name="com.example.myfirstapp.MainActivity" ...> + ... + </activity> + <!-- A child of the main activity --> + <activity + android:name="com.example.myfirstapp.DisplayMessageActivity" + android:label="@string/title_activity_display_message" + android:parentActivityName="com.example.myfirstapp.MainActivity" > + <!-- The meta-data element is needed for versions lower than 4.1 --> + <meta-data + android:name="android.support.PARENT_ACTIVITY" + android:value="com.example.myfirstapp.MainActivity" /> + </activity> +</application> +</pre> + +<p>With the parent activity declared this way, you can use the +{@link android.support.v4.app.NavUtils} APIs to synthesize a new back stack by identifying which +activity is the appropriate parent for each activity.</p> -<h2 id="back-fragments">Implement <em>Back</em> Navigation with Fragments</h2> -<p>When using fragments in your application, individual {@link android.app.FragmentTransaction} objects can represent context changes that should be added to the back stack. For example, if you are implementing a <a href="descendant.html#master-detail">master/detail flow</a> on a handset by swapping out fragments (thus emulating a {@link android.app.Activity#startActivity startActivity()} call), you should ensure that pressing the <em>Back</em> button on a detail screen returns the user to the master screen. To do so, you can use {@link android.app.FragmentTransaction#addToBackStack addToBackStack()}:</p> + +<h3 id="CreateBackStack">Create back stack when starting the activity</h3> + +<p>Adding activities to the back stack begins upon the event that takes the user into your app. +That is, instead of calling {@link android.content.Context#startActivity startActivity()}, use the +{@link android.support.v4.app.TaskStackBuilder} APIs to define each activity that should +be placed into a new back stack. Then begin the target activity by calling {@link +android.support.v4.app.TaskStackBuilder#startActivities startActivities()}, or create the +appropriate {@link android.app.PendingIntent} by calling {@link +android.support.v4.app.TaskStackBuilder#getPendingIntent getPendingIntent()}.</p> + +<p>For example, when a notification takes the user to an activity deep in your app hierarchy, +you can use this code to create a {@link android.app.PendingIntent} +that starts an activity and inserts a new back stack into the target task:</p> + +<pre> +// Intent for the activity to open when user selects the notification +Intent detailsIntent = new Intent(this, DetailsActivity.class); + +// Use TaskStackBuilder to build the back stack and get the PendingIntent +PendingIntent pendingIntent = + TaskStackBuilder.create(this) + // add all of DetailsActivity's parents to the stack, + // followed by DetailsActivity itself + .addNextIntentWithParentStack(upIntent) + .getPendingIntent(0, PendingIntent.FLAG_UPDATE_CURRENT); + +NotificationCompat.Builder builder = new NotificationCompat.Builder(this); +builder.setContentIntent(pendingIntent); +... +</pre> + +<p>The resulting {@link android.app.PendingIntent} specifies not only the activity to +start (as defined by {@code detailsIntent}), but also the back stack that should be inserted +into the task (all parents of the {@code DetailsActivity} defined by {@code detailsIntent}). +So when the {@code DetailsActivity} starts, pressing <em>Back</em> +navigates backward through each of the {@code DetailsActivity} class's parent activities.</p> + +<p class="note"><strong>Note:</strong> In order for the {@link +android.support.v4.app.TaskStackBuilder#addNextIntentWithParentStack addNextIntentWithParentStack()} +method to work, +you must declare the logical parent of each activity in your manifest file, using the +<a href="{@docRoot}guide/topics/manifest/activity-element.html#parent">{@code +android:parentActivityName}</a> attribute (and corresponding <a +href="{@docRoot}guide/topics/manifest/meta-data-element.html">{@code <meta-data>}</a> element) +as described above.</p> + + + + + +<h2 id="back-fragments">Implement Back Navigation for Fragments</h2> + +<p>When using fragments in your app, individual {@link android.app.FragmentTransaction} +objects may represent context changes that should be added to the back stack. For example, if you +are implementing a <a href="descendant.html#master-detail">master/detail flow</a> on a handset by +swapping out fragments, you should ensure that pressing the <em>Back</em> button on a detail +screen returns the user to the master screen. To do so, call {@link +android.app.FragmentTransaction#addToBackStack addToBackStack()} before you commit +the transaction:</p> <pre> // Works with either the framework FragmentManager or the // support package FragmentManager (getSupportFragmentManager). -getFragmentManager().beginTransaction() - .add(detailFragment, "detail") - - // Add this transaction to the back stack and commit. - .addToBackStack() - .commit(); +getSupportFragmentManager().beginTransaction() + .add(detailFragment, "detail") + // Add this transaction to the back stack + .addToBackStack() + .commit(); </pre> -<p>The activity's {@link android.app.FragmentManager} handles <em>Back</em> button presses if there are {@link android.app.FragmentTransaction} objects on the back stack. When this happens, the {@link android.app.FragmentManager} pops the most recent transaction off the back stack and performs the reverse action (e.g., removing a fragment if the transaction added it).</p> +<p>When there are {@link android.app.FragmentTransaction} objects on the back stack and the user +presses the <em>Back</em> button, +the {@link android.app.FragmentManager} pops the most recent transaction off the back stack and +performs the reverse action (such as removing a fragment if the transaction added it).</p> -<p>If your application updates other user interface elements to reflect the current state of your fragments, such as the action bar, remember to update the UI when you commit the transaction. You should update your user interface after the fragment manager back stack changes in addition to when you commit the transaction. You can listen for when a <code>FragmentTransaction</code> is reverted by setting up an {@link android.app.FragmentManager.OnBackStackChangedListener}:</p> +<p class="note"><strong>Note:</strong> You <strong>should not add transactions to the back +stack</strong> when the transaction is for horizontal navigation (such as when switching tabs) +or when modifying the content appearance (such as when adjusting filters). For more information, +about when <em>Back</em> navigation is appropriate, +see the <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> design guide.</p> + +<p>If your application updates other user interface elements to reflect the current state of your +fragments, such as the action bar, remember to update the UI when you commit the transaction. You +should update your user interface after the back stack changes in addition to +when you commit the transaction. You can listen for when a {@link android.app.FragmentTransaction} +is reverted by setting up an {@link android.app.FragmentManager.OnBackStackChangedListener}:</p> <pre> -getFragmentManager().addOnBackStackChangedListener( +getSupportFragmentManager().addOnBackStackChangedListener( new FragmentManager.OnBackStackChangedListener() { public void onBackStackChanged() { // Update your UI here. @@ -63,9 +217,14 @@ getFragmentManager().addOnBackStackChangedListener( }); </pre> -<h2 id="back-webviews">Implement <em>Back</em> Navigation with WebViews</h2> -<p>If a part of your application is contained in a {@link android.webkit.WebView}, it may be appropriate for <em>Back</em> to traverse browser history. To do so, you can override {@link android.app.Activity#onBackPressed onBackPressed()} and proxy to the <code>WebView</code> if it has history state:</p> + +<h2 id="back-webviews">Implement Back Navigation for WebViews</h2> + +<p>If a part of your application is contained in a {@link android.webkit.WebView}, it may be +appropriate for <em>Back</em> to traverse browser history. To do so, you can override {@link +android.app.Activity#onBackPressed onBackPressed()} and proxy to the +{@link android.webkit.WebView} if it has history state:</p> <pre> {@literal @}Override @@ -80,4 +239,9 @@ public void onBackPressed() { } </pre> -<p>Be careful when using this mechanism with highly dynamic web pages that can grow a large history. Pages that generate an extensive history, such as those that make frequent changes to the document hash, may make it tedious for users to get out of your activity.</p> +<p>Be careful when using this mechanism with highly dynamic web pages that can grow a large +history. Pages that generate an extensive history, such as those that make frequent changes to +the document hash, may make it tedious for users to get out of your activity.</p> + +<p>For more information about using {@link android.webkit.WebView}, read <a +href="{@docRoot}guide/webapps/webview.html">Building Web Apps in WebView</a>. diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index ee6913c..61517e0 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -624,20 +624,25 @@ <div class="nav-section-header"> <a href="<?cs var:toroot ?>training/implementing-navigation/index.html" description= - "How to implement various navigation patterns such as swipe views and up navigation." + "How to implement various navigation patterns such as swipe views, + a navigation drawer, and up navigation." >Implementing Effective Navigation</a> </div> <ul> <li><a href="<?cs var:toroot ?>training/implementing-navigation/lateral.html"> - Implementing Lateral Navigation + Creating Swipe Views with Tabs + </a> + </li> + <li><a href="<?cs var:toroot ?>training/implementing-navigation/nav-drawer.html"> + Creating a Navigation Drawer </a> </li> <li><a href="<?cs var:toroot ?>training/implementing-navigation/ancestral.html"> - Implementing Ancestral Navigation + Providing Up Navigation </a> </li> <li><a href="<?cs var:toroot ?>training/implementing-navigation/temporal.html"> - Implementing Temporal Navigation + Providing Proper Back Navigation </a> </li> <li><a href="<?cs var:toroot ?>training/implementing-navigation/descendant.html"> diff --git a/services/java/com/android/server/ServiceWatcher.java b/services/java/com/android/server/ServiceWatcher.java index 67f926a..2e7c6d1 100644 --- a/services/java/com/android/server/ServiceWatcher.java +++ b/services/java/com/android/server/ServiceWatcher.java @@ -177,7 +177,7 @@ public class ServiceWatcher implements ServiceConnection { mVersion = version; if (D) Log.d(mTag, "binding " + packageName + " (version " + version + ")"); mContext.bindService(intent, this, Context.BIND_AUTO_CREATE | Context.BIND_NOT_FOREGROUND - | Context.BIND_NOT_VISIBLE, mCurrentUserId); + | Context.BIND_ALLOW_OOM_MANAGEMENT | Context.BIND_NOT_VISIBLE, mCurrentUserId); } public static boolean isSignatureMatch(Signature[] signatures, |
