diff options
Diffstat (limited to 'docs/html')
543 files changed, 16635 insertions, 15279 deletions
diff --git a/docs/html/design/building-blocks/buttons.html b/docs/html/design/building-blocks/buttons.html deleted file mode 100644 index cc43fcb..0000000 --- a/docs/html/design/building-blocks/buttons.html +++ /dev/null @@ -1,191 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Buttons - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Buttons</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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> - -<div style="text-align: center"> - <img src="../static/content/buttons_basic.png"> -</div> - -<h2>Basic Buttons</h2> -<p>Basic buttons are traditional buttons with borders and background. Android supports two styles for -basic buttons: default and small. Default buttons have slightly larger font size and are optimized -for display outside of form content. Small buttons are intended for display alongside other content. -They have a smaller font and smaller minimum height. Use small buttons in forms where they need to -align with other UI elements.</p> - -<img src="../static/content/buttons_default_small.png"> -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - <div class="figure-caption"> - Default buttons in Holo Dark & Light. - </div> - </div> - <div class="layout-content-col span-6"> - <div class="figure-caption"> - Small buttons in Holo Dark & Light. - </div> - </div> -</div> - -<h2>Borderless Buttons</h2> -<p>Borderless buttons resemble basic buttons except that they have no borders or background. You can -use borderless buttons with both icons and text. Borderless buttons are visually more lightweight -than basic buttons and integrate nicely with other content.</p> - -<img src="../static/content/buttons_borderless.png"> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/buttons.jd b/docs/html/design/building-blocks/buttons.jd new file mode 100644 index 0000000..18beab0 --- /dev/null +++ b/docs/html/design/building-blocks/buttons.jd @@ -0,0 +1,40 @@ +page.title=Buttons +@jd:body + +<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> + +<div style="text-align: center"> + <img src="{@docRoot}design/media/buttons_basic.png"> +</div> + +<h2 id="basic">Basic Buttons</h2> + +<p>Basic buttons are traditional buttons with borders and background. Android supports two styles for +basic buttons: default and small. Default buttons have slightly larger font size and are optimized +for display outside of form content. Small buttons are intended for display alongside other content. +They have a smaller font and smaller minimum height. Use small buttons in forms where they need to +align with other UI elements.</p> + +<img src="{@docRoot}design/media/buttons_default_small.png"> +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + <div class="figure-caption"> + Default buttons in Holo Dark & Light. + </div> + </div> + <div class="layout-content-col span-6"> + <div class="figure-caption"> + Small buttons in Holo Dark & Light. + </div> + </div> +</div> + +<h2 id="borderless">Borderless Buttons</h2> + +<p>Borderless buttons resemble basic buttons except that they have no borders or background. You can +use borderless buttons with both icons and text. Borderless buttons are visually more lightweight +than basic buttons and integrate nicely with other content.</p> + +<img src="{@docRoot}design/media/buttons_borderless.png"> diff --git a/docs/html/design/building-blocks/dialogs.html b/docs/html/design/building-blocks/dialogs.html deleted file mode 100644 index fc00780..0000000 --- a/docs/html/design/building-blocks/dialogs.html +++ /dev/null @@ -1,265 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Dialogs - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Dialogs</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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> - -<img src="../static/content/dialogs_main.png"> - -<div class="with-callouts"> - -<ol> -<li> -<h4>Optional title region</h4> -<p>The title introduces the content of your dialog. It can, for example, identify the name of a - setting that the user is about to change, or request a decision.</p> -</li> -<li> -<h4>Content area</h4> -<p>Dialog content varies widely. For settings dialogs, a dialog may contain UI elements such as - sliders, text fields, checkboxes, or radio buttons that allow the user to change app or system - settings. In other cases, such as alerts, the content may consist solely of text that provides - further context for a user decision.</p> -</li> -<li> -<h4>Action buttons</h4> -<p>Action buttons are typically Cancel and/or OK, with OK indicating the preferred or most likely - action. However, if the options consist of specific actions such as Close or Wait rather than - a confirmation or cancellation of the action described in the content, then all the buttons - should be active verbs. As a rule, the dismissive action of a dialog is always on the left - whereas the affirmative actions are on the right.</p> -</li> -</ol> - -</div> - -<img src="../static/content/dialogs_examples.png"> -<div class="figure-caption"> - Samples of typical dialog use in Android. -</div> - -<h2 id="alerts">Alerts</h2> - -<p>Alerts inform the user about a situation that requires their confirmation or acknowledgement before -proceeding. They differ slightly in appearance based upon the severity and impact of the message -conveyed.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/dialogs_w_no_title.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Alerts without title bars</h4> -<p>Most alerts don't need titles. Usually the decision doesn't have a severe impact and can be summed -up succinctly in a sentence or two. The content area should either ask a question (such as "Delete -this conversation?") or make a clear statement whose relationship to the action buttons is obvious.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/dialogs_w_title.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Alerts with title bars</h4> -<p>Use alerts with title bars sparingly. They are appropriate only when a high-risk operation involving -potential loss of data, connectivity, extra charges, and so on requires a clear question or -statement (the title) and some additional explanation (in the content area).</p> -<p>Keep the question or statement short: for example, "Erase USB storage?" Avoid apologies. A user -should be able to skip the content completely and still have a clear idea of what choices are -available based on the title and the text of the action buttons.</p> - - </div> -</div> - - -<h2 id="popups">Popups</h2> - -<p>Popups are lightweight version of dialogs that require a single selection from the user. Popups -don't have have explicit buttons that accept or cancel the operation. Instead, making a selection -advances the workflow, and simply touching outside the popup dismisses it.</p> - -<img src="../static/content/dialogs_popups_example.png"> - - -<h2 id="toasts">Toasts</h2> - - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - - <div class="vspace size-6"></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> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/dialogs_toasts.png"> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/dialogs.jd b/docs/html/design/building-blocks/dialogs.jd new file mode 100644 index 0000000..9b653ee --- /dev/null +++ b/docs/html/design/building-blocks/dialogs.jd @@ -0,0 +1,112 @@ +page.title=Dialogs +@jd:body + +<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> + +<img src="{@docRoot}design/media/dialogs_main.png"> + +<div class="with-callouts"> + +<ol> +<li> +<h4>Optional title region</h4> +<p>The title introduces the content of your dialog. It can, for example, identify the name of a + setting that the user is about to change, or request a decision.</p> +</li> +<li> +<h4>Content area</h4> +<p>Dialog content varies widely. For settings dialogs, a dialog may contain UI elements such as + sliders, text fields, checkboxes, or radio buttons that allow the user to change app or system + settings. In other cases, such as alerts, the content may consist solely of text that provides + further context for a user decision.</p> +</li> +<li> +<h4>Action buttons</h4> +<p>Action buttons are typically Cancel and/or OK, with OK indicating the preferred or most likely + action. However, if the options consist of specific actions such as Close or Wait rather than + a confirmation or cancellation of the action described in the content, then all the buttons + should be active verbs. As a rule, the dismissive action of a dialog is always on the left + whereas the affirmative actions are on the right.</p> +</li> +</ol> + +</div> + +<img src="{@docRoot}design/media/dialogs_examples.png"> +<div class="figure-caption"> + Samples of typical dialog use in Android. +</div> + +<h2 id="alerts">Alerts</h2> + +<p>Alerts inform the user about a situation that requires their confirmation or acknowledgement before +proceeding. They differ slightly in appearance based upon the severity and impact of the message +conveyed.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/dialogs_w_no_title.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Alerts without title bars</h4> +<p>Most alerts don't need titles. Usually the decision doesn't have a severe impact and can be summed +up succinctly in a sentence or two. The content area should either ask a question (such as "Delete +this conversation?") or make a clear statement whose relationship to the action buttons is obvious.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/dialogs_w_title.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Alerts with title bars</h4> +<p>Use alerts with title bars sparingly. They are appropriate only when a high-risk operation involving +potential loss of data, connectivity, extra charges, and so on requires a clear question or +statement (the title) and some additional explanation (in the content area).</p> +<p>Keep the question or statement short: for example, "Erase USB storage?" Avoid apologies. A user +should be able to skip the content completely and still have a clear idea of what choices are +available based on the title and the text of the action buttons.</p> + + </div> +</div> + + +<h2 id="popups">Popups</h2> + +<p>Popups are lightweight version of dialogs that require a single selection from the user. Popups +don't have have explicit buttons that accept or cancel the operation. Instead, making a selection +advances the workflow, and simply touching outside the popup dismisses it.</p> + +<img src="{@docRoot}design/media/dialogs_popups_example.png"> + + +<h2 id="toasts">Toasts</h2> + + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + + <div class="vspace size-6"></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> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/dialogs_toasts.png"> + + </div> +</div> diff --git a/docs/html/design/building-blocks/grid-lists.html b/docs/html/design/building-blocks/grid-lists.html deleted file mode 100644 index b4cfdcb..0000000 --- a/docs/html/design/building-blocks/grid-lists.html +++ /dev/null @@ -1,233 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Grid Lists - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Grid Lists</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<img src="../static/content/gridview_overview.png"> - -<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> - - - -<h2 id="generic_grid">Generic Grids</h2> - - -<p>The items in a grid list are arranged in two dimensions, one of which is fixed when scrolling -content. The scrolling direction dictates the ordering of the items within the grid list. Since the -scrolling direction is not deterministic, make it easy for the user to determine the orientation by -cutting off grid items to communicate where the overflow is located.</p> -<p>Avoid creating grid lists that scroll in two dimensions.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - - <img src="../static/content/gridview_vertical.png"> - - </div> - <div class="layout-content-col span-6"> - -<h4>Vertical scrolling</h4> -<p>Vertically scrolling grid list items are sorted in traditional western reading direction: -left-to-right and top-down. When displaying the list, cut off the items in the bottom row to -communicate that the user can scroll the list down to show additional items. Be sure to retain this -scheme when the user rotates the screen.</p> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - - <img src="../static/content/gridview_horizontal.png"> - - </div> - <div class="layout-content-col span-6"> - -<h4>Horizontal scrolling</h4> -<p>Horizontally scrolling lists fix the vertical axis of the item grid. Compared to vertically -scrolling lists, the sorting changes slightly to a top-down and left-to-right arrangement. Employ -the same technique of cutting off the items in the rightmost column to indicate the scrolling -direction.</p> -<p>Don't use scrolling tabs as a means to switch views in conjunction with horizontally scrolling grid -lists, because the horizontal gesture for view and content navigation will conflict. If you show -scrolling tabs for view navigation together with a grid list, use vertical grid scrolling for list -navigation.</p> - - </div> -</div> - - -<h2 id="with_labels">Grid List with Labels</h2> - -<p>Use labels to display additional contextual information for your grid list items.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - - <img src="../static/content/gridview_style.png"> - - </div> - <div class="layout-content-col span-6"> - -<h4>Style</h4> -<p>Use semi-transparent panels on top of the grid list items to display your labels. This allows you to -control the contrast and ensures legibility of the labels while letting the content "shine through".</p> - - </div> -</div> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/grid-lists.jd b/docs/html/design/building-blocks/grid-lists.jd new file mode 100644 index 0000000..775ebcc --- /dev/null +++ b/docs/html/design/building-blocks/grid-lists.jd @@ -0,0 +1,79 @@ +page.title=Grid Lists +@jd:body + +<img src="{@docRoot}design/media/gridview_overview.png"> + +<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> + + + +<h2 id="generic_grid">Generic Grids</h2> + + +<p>The items in a grid list are arranged in two dimensions, one of which is fixed when scrolling +content. The scrolling direction dictates the ordering of the items within the grid list. Since the +scrolling direction is not deterministic, make it easy for the user to determine the orientation by +cutting off grid items to communicate where the overflow is located.</p> +<p>Avoid creating grid lists that scroll in two dimensions.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/gridview_vertical.png"> + + </div> + <div class="layout-content-col span-6"> + +<h4>Vertical scrolling</h4> +<p>Vertically scrolling grid list items are sorted in traditional western reading direction: +left-to-right and top-down. When displaying the list, cut off the items in the bottom row to +communicate that the user can scroll the list down to show additional items. Be sure to retain this +scheme when the user rotates the screen.</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/gridview_horizontal.png"> + + </div> + <div class="layout-content-col span-6"> + +<h4>Horizontal scrolling</h4> +<p>Horizontally scrolling lists fix the vertical axis of the item grid. Compared to vertically +scrolling lists, the sorting changes slightly to a top-down and left-to-right arrangement. Employ +the same technique of cutting off the items in the rightmost column to indicate the scrolling +direction.</p> +<p>Don't use scrolling tabs as a means to switch views in conjunction with horizontally scrolling grid +lists, because the horizontal gesture for view and content navigation will conflict. If you show +scrolling tabs for view navigation together with a grid list, use vertical grid scrolling for list +navigation.</p> + + </div> +</div> + + +<h2 id="with-labels">Grid List with Labels</h2> + +<p>Use labels to display additional contextual information for your grid list items.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/gridview_style.png"> + + </div> + <div class="layout-content-col span-6"> + +<h4>Style</h4> +<p>Use semi-transparent panels on top of the grid list items to display your labels. This allows you to +control the contrast and ensures legibility of the labels while letting the content "shine through".</p> + + </div> +</div> diff --git a/docs/html/design/building-blocks/index.html b/docs/html/design/building-blocks/index.html deleted file mode 100644 index c99d85c..0000000 --- a/docs/html/design/building-blocks/index.html +++ /dev/null @@ -1,171 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Building Blocks - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - -<style> -#landing-graphic-container { - position: relative; -} - -#text-overlay { - position: absolute; - left: 10px; - top: 472px; - width: 450px; -} -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - -<div class="layout-content-row content-header just-links"> - <div class="layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> -</div> - - - - -<div id="landing-graphic-container"> - <div id="text-overlay"> - Your inventory of ready-to-use elements for creating outstanding apps. - <br><br> - <a href="../building-blocks/tabs.html" class="landing-page-link">Tabs</a> - </div> - - <a href="../building-blocks/tabs.html"> - <img src="../static/content/building_blocks_landing.png"> - </a> -</div> - - - - - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/index.jd b/docs/html/design/building-blocks/index.jd new file mode 100644 index 0000000..52b4915 --- /dev/null +++ b/docs/html/design/building-blocks/index.jd @@ -0,0 +1,29 @@ +page.title=Building Blocks +header.justLinks=1 +footer.hide=1 +@jd:body + +<style> +#landing-graphic-container { + position: relative; +} + +#text-overlay { + position: absolute; + left: 10px; + top: 472px; + width: 450px; +} +</style> + +<div id="landing-graphic-container"> + <div id="text-overlay"> + Your inventory of ready-to-use elements for creating outstanding apps. + <br><br> + <a href="{@docRoot}design/building-blocks/tabs.html" class="landing-page-link">Tabs</a> + </div> + + <a href="{@docRoot}design/building-blocks/tabs.html"> + <img src="{@docRoot}design/media/building_blocks_landing.png"> + </a> +</div> diff --git a/docs/html/design/building-blocks/lists.html b/docs/html/design/building-blocks/lists.html deleted file mode 100644 index 914ae9e..0000000 --- a/docs/html/design/building-blocks/lists.html +++ /dev/null @@ -1,184 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Lists - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Lists</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Lists present multiple line items in a vertical arrangement. They can be used for data selection as -well as drilldown navigation.</p> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row clearfix"> - <div class="layout-content-col span-9"> - - <img src="../static/content/lists_main.png"> - - </div> - <div class="layout-content-col span-4 with-callouts"> - -<ol> -<li> -<h4>Section Divider</h4> -<p>Use section dividers to organize the content of your list into groups and facilitate scanning.</p> -</li> -<li> -<h4>Line Items</h4> -<p>List items can accommodate a wide range of data types in different arrangements, including - simple single-line items, multi-line items, and custom items with icons, checkboxes, and action - buttons.</p> -</li> -</ol> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/lists.jd b/docs/html/design/building-blocks/lists.jd new file mode 100644 index 0000000..aaa86b8 --- /dev/null +++ b/docs/html/design/building-blocks/lists.jd @@ -0,0 +1,31 @@ +page.title=Lists +@jd:body + +<p>Lists present multiple line items in a vertical arrangement. They can be used for data selection as +well as drilldown navigation.</p> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row clearfix"> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/lists_main.png"> + + </div> + <div class="layout-content-col span-4 with-callouts"> + +<ol> +<li> +<h4>Section Divider</h4> +<p>Use section dividers to organize the content of your list into groups and facilitate scanning.</p> +</li> +<li> +<h4>Line Items</h4> +<p>List items can accommodate a wide range of data types in different arrangements, including + simple single-line items, multi-line items, and custom items with icons, checkboxes, and action + buttons.</p> +</li> +</ol> + + </div> +</div> diff --git a/docs/html/design/building-blocks/pickers.html b/docs/html/design/building-blocks/pickers.html deleted file mode 100644 index 4c95a9f..0000000 --- a/docs/html/design/building-blocks/pickers.html +++ /dev/null @@ -1,187 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Pickers - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Pickers</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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> - -<div class="layout-content-row"> - <div class="layout-content-col span-2"> </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/picker_space.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Space considerations</h4> -<p>Pickers can be used inline on a form, but their relatively large footprint is best suited for -display in a dialog. For inline display, consider using more compact controls such as text fields or -spinners.</p> - - </div> -</div> - -<h2>Date and time pickers</h2> - -<p>Android provides these as ready-to-use dialogs. Each picker is a dialog with a set of controls for -entering the parts of the date (month, day, year) or time (hour, minute, AM/PM). Using these in your -app helps ensure that a user's specification of a data or time input is valid and formatted -correctly. The format of a time and date picker adjusts automatically to the locale.</p> - -<img src="../static/content/picker_datetime.png"> - - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/pickers.jd b/docs/html/design/building-blocks/pickers.jd new file mode 100644 index 0000000..85f2187 --- /dev/null +++ b/docs/html/design/building-blocks/pickers.jd @@ -0,0 +1,32 @@ +page.title=Pickers +@jd:body + +<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> + +<div class="layout-content-row"> + <div class="layout-content-col span-2"> </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/picker_space.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Space considerations</h4> +<p>Pickers can be used inline on a form, but their relatively large footprint is best suited for +display in a dialog. For inline display, consider using more compact controls such as text fields or +spinners.</p> + + </div> +</div> + +<h2 id="date-time">Date and time pickers</h2> + +<p>Android provides these as ready-to-use dialogs. Each picker is a dialog with a set of controls for +entering the parts of the date (month, day, year) or time (hour, minute, AM/PM). Using these in your +app helps ensure that a user's specification of a data or time input is valid and formatted +correctly. The format of a time and date picker adjusts automatically to the locale.</p> + +<img src="{@docRoot}design/media/picker_datetime.png"> diff --git a/docs/html/design/building-blocks/progress.html b/docs/html/design/building-blocks/progress.html deleted file mode 100644 index 7aae913..0000000 --- a/docs/html/design/building-blocks/progress.html +++ /dev/null @@ -1,233 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Progress and Activity - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - - - - -<div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2 id="system">Feedback</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> -</div> - -<p>When an operation of interest to the user is taking place over a relatively long period of time, -provide visual feedback that it's still happening and in the process of being completed.</p> -<h2>Progress</h2> -<p>If you know the percentage of the operation that has been completed, use a determinate progress bar -to give the user a sense of how much longer it will take.</p> - -<img src="../static/content/progress_download.png"> - -<p>The progress bar should always travel from 0% to 100% completion. Avoid setting the bar to a lower -value than a previous value, or using the same progress bar to represent the progress of multiple -events, since doing so makes the display meaningless. If you're not sure how long a particular -operation will take, use an indeterminate progress indicator.</p> - -<div class="vspace size-2"> </div> - -<img src="../static/content/progress_themes.png"> -<div class="figure-caption"> - Progress bar in Holo Dark and Holo Light. -</div> - -<h2 id="activity">Activity</h2> - -<p>If you don't know how much longer an operation will continue, use an indeterminate progress -indicator. There are two styles available: a flat bar and a circle. Use the one that best fits the -available space.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - - <img src="../static/content/progress_activity.png"> - - </div> - <div class="layout-content-col span-7 with-callouts"> - - <ol> - <li class="value-1"><h4>Activity bar (shown with the Holo Dark theme)</h4> - <p> - -An indeterminate activity bar is used at the start of an application download because Market hasn't -been able to contact the server yet, and it's not possible to determine how long it will take for -the download to begin. - - </p> - </li> - </ol> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - - <img src="../static/content/progress_activity2.png"> - - </div> - <div class="layout-content-col span-7 with-callouts"> - - <ol> - <li class="value-2"><h4>Activity circle (shown with the Holo Light theme)</h4> - <p> - -An indeterminate activity circle is used in the Gmail application when a message is being -loaded because it's not possible to determine how long it will take to download the email. - - </p> - </li> - </ol> - - </div> -</div> - -<p>You should only use one activity indicator on screen per activity, and it should appropriately sized -for the surrounding context. For example, the largest activity circle works well when displayed in a -blank content area, but not in a smaller dialog box.</p> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/progress.jd b/docs/html/design/building-blocks/progress.jd new file mode 100644 index 0000000..b188538 --- /dev/null +++ b/docs/html/design/building-blocks/progress.jd @@ -0,0 +1,80 @@ +page.title=Progress and Activity +header.title=Feedback +@jd:body + +<p>When an operation of interest to the user is taking place over a relatively long period of time, +provide visual feedback that it's still happening and in the process of being completed.</p> +<h2 id="progress">Progress</h2> + +<p>If you know the percentage of the operation that has been completed, use a determinate progress bar +to give the user a sense of how much longer it will take.</p> + +<img src="{@docRoot}design/media/progress_download.png"> + +<p>The progress bar should always travel from 0% to 100% completion. Avoid setting the bar to a lower +value than a previous value, or using the same progress bar to represent the progress of multiple +events, since doing so makes the display meaningless. If you're not sure how long a particular +operation will take, use an indeterminate progress indicator.</p> + +<div class="vspace size-2"> </div> + +<img src="{@docRoot}design/media/progress_themes.png"> +<div class="figure-caption"> + Progress bar in Holo Dark and Holo Light. +</div> + +<h2 id="activity">Activity</h2> + +<p>If you don't know how much longer an operation will continue, use an indeterminate progress +indicator. There are two styles available: a flat bar and a circle. Use the one that best fits the +available space.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/progress_activity.png"> + + </div> + <div class="layout-content-col span-7 with-callouts"> + + <ol> + <li class="value-1"><h4>Activity bar (shown with the Holo Dark theme)</h4> + <p> + +An indeterminate activity bar is used at the start of an application download because the Play Store +app hasn't been able to contact the server yet, and it's not possible to determine how long it will +take for the download to begin. + + </p> + </li> + </ol> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/progress_activity2.png"> + + </div> + <div class="layout-content-col span-7 with-callouts"> + + <ol> + <li class="value-2"><h4>Activity circle (shown with the Holo Light theme)</h4> + <p> + +An indeterminate activity circle is used in the Gmail application when a message is being +loaded because it's not possible to determine how long it will take to download the email. + + </p> + </li> + </ol> + + </div> +</div> + +<p>You should only use one activity indicator on screen per activity, and it should appropriately sized +for the surrounding context. For example, the largest activity circle works well when displayed in a +blank content area, but not in a smaller dialog box.</p> diff --git a/docs/html/design/building-blocks/scrolling.html b/docs/html/design/building-blocks/scrolling.html deleted file mode 100644 index 3f1167c..0000000 --- a/docs/html/design/building-blocks/scrolling.html +++ /dev/null @@ -1,188 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Scrolling - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Scrolling</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Scrolling allows the user to navigate to content in the overflow using a swipe gesture. The -scrolling speed is proportional to the speed of the gesture.</p> -<h2>Scroll Indicator</h2> -<p>Appears during scrolling to indicate what portion of the content is currently in view.</p> - -<div class="framed-galaxynexus-land-span-13"> - <video class="play-on-hover" autoplay> - <source src="../static/content/scroll_indicator.mp4" type="video/mp4"> - <source src="../static/content/scroll_indicator.webm" type="video/webm"> - <source src="../static/content/scroll_indicator.ogv" type="video/ogg"> - </video> -</div> -<div class="figure-caption"> - <div class="video-instructions"> </div> -</div> - -<h2>Index Scrolling</h2> -<p>In addition to traditional scrolling, a long alphabetical list can also offer index scrolling: a way -to quickly navigate to the items that begin with a particular letter. With index scrolling, a scroll -indicator appears even when the user isn't scrolling. Touching or dragging it causes the current -letter to pop up in a prominent way.</p> - -<div class="framed-galaxynexus-land-span-13"> - <video class="play-on-hover" autoplay> - <source src="../static/content/scroll_index.mp4" type="video/mp4"> - <source src="../static/content/scroll_index.webm" type="video/webm"> - <source src="../static/content/scroll_index.ogv" type="video/ogg"> - </video> -</div> -<div class="figure-caption"> - <div class="video-instructions"> </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/scrolling.jd b/docs/html/design/building-blocks/scrolling.jd new file mode 100644 index 0000000..7695157 --- /dev/null +++ b/docs/html/design/building-blocks/scrolling.jd @@ -0,0 +1,37 @@ +page.title=Scrolling +@jd:body + +<p>Scrolling allows the user to navigate to content in the overflow using a swipe gesture. The +scrolling speed is proportional to the speed of the gesture.</p> +<h2 id="indicator">Scroll Indicator</h2> + +<p>Appears during scrolling to indicate what portion of the content is currently in view.</p> + +<div class="framed-galaxynexus-land-span-13"> + <video class="play-on-hover" autoplay> + <source src="{@docRoot}design/media/scroll_indicator.mp4" type="video/mp4"> + <source src="{@docRoot}design/media/scroll_indicator.webm" type="video/webm"> + <source src="{@docRoot}design/media/scroll_indicator.ogv" type="video/ogg"> + </video> +</div> +<div class="figure-caption"> + <div class="video-instructions"> </div> +</div> + +<h2 id="index-scrolling">Index Scrolling</h2> + +<p>In addition to traditional scrolling, a long alphabetical list can also offer index scrolling: a way +to quickly navigate to the items that begin with a particular letter. With index scrolling, a scroll +indicator appears even when the user isn't scrolling. Touching or dragging it causes the current +letter to pop up in a prominent way.</p> + +<div class="framed-galaxynexus-land-span-13"> + <video class="play-on-hover" autoplay> + <source src="{@docRoot}design/media/scroll_index.mp4" type="video/mp4"> + <source src="{@docRoot}design/media/scroll_index.webm" type="video/webm"> + <source src="{@docRoot}design/media/scroll_index.ogv" type="video/ogg"> + </video> +</div> +<div class="figure-caption"> + <div class="video-instructions"> </div> +</div> diff --git a/docs/html/design/building-blocks/seek-bars.html b/docs/html/design/building-blocks/seek-bars.html deleted file mode 100644 index 84cf5d2..0000000 --- a/docs/html/design/building-blocks/seek-bars.html +++ /dev/null @@ -1,190 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Seek Bars and Sliders - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Seek Bars and Sliders</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Interactive sliders make it possible to select a value from a continuous or discrete range of values -by moving the slider thumb. The smallest value is to the left, the largest to the right. The -interactive nature of the slider makes it a great choice for settings that reflect intensity levels, -such as volume, brightness, or color saturation.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-9"> - - <img src="../static/content/seekbar_example.png"> - - </div> - <div class="layout-content-col span-4"> - -<div class="vspace size-2"> </div> - -<h4>Example</h4> -<p>Interactive slider to set the ringer volume. The value can either be set through the hardware volume controls or interactively via a gesture.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-9"> - - <img src="../static/content/seekbar_style.png"> - <div class="figure-caption"> - Seek bars in Holo Light & Dark - </div> - - </div> - <div class="layout-content-col span-4"> </div> -</div> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/seek-bars.jd b/docs/html/design/building-blocks/seek-bars.jd new file mode 100644 index 0000000..3407ddd --- /dev/null +++ b/docs/html/design/building-blocks/seek-bars.jd @@ -0,0 +1,36 @@ +page.title=Seek Bars and Sliders +@jd:body + +<p>Interactive sliders make it possible to select a value from a continuous or discrete range of values +by moving the slider thumb. The smallest value is to the left, the largest to the right. The +interactive nature of the slider makes it a great choice for settings that reflect intensity levels, +such as volume, brightness, or color saturation.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/seekbar_example.png"> + + </div> + <div class="layout-content-col span-4"> + +<div class="vspace size-2"> </div> + +<h4>Example</h4> +<p>Interactive slider to set the ringer volume. The value can either be set through the hardware volume controls or interactively via a gesture.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/seekbar_style.png"> + <div class="figure-caption"> + Seek bars in Holo Light & Dark + </div> + + </div> + <div class="layout-content-col span-4"> </div> +</div> diff --git a/docs/html/design/building-blocks/spinners.html b/docs/html/design/building-blocks/spinners.html deleted file mode 100644 index bf21fe8..0000000 --- a/docs/html/design/building-blocks/spinners.html +++ /dev/null @@ -1,190 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Spinners - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Spinners</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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> - - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - - <img src="../static/content/spinners_form.png"> - -<h4>Spinners in forms</h4> -<p>Spinners are useful for data picking in forms. They are compact and integrate nicely with other -components. Use spinners in forms for both simple data input and in combination with other input -fields. For example, a text field might let you edit an email address for a contact, while its -associated spinner allows you to select whether it's a Home or Work address.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/spinners_actionbar.png"> - -<h4>Spinners in action bars</h4> -<p>Use spinners in action bars to switch views. For example, Gmail uses a spinner to permit switching -between accounts or commonly used labels. Spinners are useful when changing the view is important to -your app, but not necessarily a frequent occurrence. In cases where view switching is frequent, use -tabs.</p> - - </div> -</div> - -<img src="../static/content/spinners_hololightanddark.png"> -<div class="figure-caption"> - Spinners in the Holo Dark and Holo Light themes, in various states. -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/spinners.jd b/docs/html/design/building-blocks/spinners.jd new file mode 100644 index 0000000..621a57c --- /dev/null +++ b/docs/html/design/building-blocks/spinners.jd @@ -0,0 +1,37 @@ +page.title=Spinners +@jd:body + +<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> + + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/spinners_form.png"> + +<h4>Spinners in forms</h4> +<p>Spinners are useful for data picking in forms. They are compact and integrate nicely with other +components. Use spinners in forms for both simple data input and in combination with other input +fields. For example, a text field might let you edit an email address for a contact, while its +associated spinner allows you to select whether it's a Home or Work address.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/spinners_actionbar.png"> + +<h4>Spinners in action bars</h4> +<p>Use spinners in action bars to switch views. For example, Gmail uses a spinner to permit switching +between accounts or commonly used labels. Spinners are useful when changing the view is important to +your app, but not necessarily a frequent occurrence. In cases where view switching is frequent, use +tabs.</p> + + </div> +</div> + +<img src="{@docRoot}design/media/spinners_hololightanddark.png"> +<div class="figure-caption"> + Spinners in the Holo Dark and Holo Light themes, in various states. +</div> diff --git a/docs/html/design/building-blocks/switches.html b/docs/html/design/building-blocks/switches.html deleted file mode 100644 index 3d7bc9c..0000000 --- a/docs/html/design/building-blocks/switches.html +++ /dev/null @@ -1,181 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Switches - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Switches</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Switches allow the user to select options. There are three kinds of switches: checkboxes, radio -buttons, and on/off switches.</p> -<h2>Checkboxes</h2> -<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> - -<div style="text-align: center"> - <img src="../static/content/switches_checkboxes.png"> -</div> - -<h2>Radio Buttons</h2> -<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> - -<div style="text-align: center"> - <img src="../static/content/switches_radios.png"> -</div> - -<h2>On/off Switches</h2> -<p>On/off switches toggle the state of a single settings option.</p> - -<div style="text-align: center"> - <img src="../static/content/switches_switches.png"> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/switches.jd b/docs/html/design/building-blocks/switches.jd new file mode 100644 index 0000000..607e0b6 --- /dev/null +++ b/docs/html/design/building-blocks/switches.jd @@ -0,0 +1,31 @@ +page.title=Switches +@jd:body + +<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> + +<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> + +<div style="text-align: center"> + <img src="{@docRoot}design/media/switches_checkboxes.png"> +</div> + +<h2 id="radio-buttons">Radio Buttons</h2> + +<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> + +<div style="text-align: center"> + <img src="{@docRoot}design/media/switches_radios.png"> +</div> + +<h2 id="switches">On/off Switches</h2> + +<p>On/off switches toggle the state of a single settings option.</p> + +<div style="text-align: center"> + <img src="{@docRoot}design/media/switches_switches.png"> +</div> diff --git a/docs/html/design/building-blocks/tabs.html b/docs/html/design/building-blocks/tabs.html deleted file mode 100644 index c094cce..0000000 --- a/docs/html/design/building-blocks/tabs.html +++ /dev/null @@ -1,213 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Tabs - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Tabs</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<img src="../static/content/tabs_overview.png"> - -<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> - - -<h2 id="scrollable">Scrollable Tabs</h2> - - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<p>Scrolling tab controls can contain a larger number of items than a standard tab control. To navigate -to the next/previous view, swipe left or right.</p> - - </div> - <div class="layout-content-col span-7"> - - <video width="400" class="with-shadow play-on-hover" autoplay> - <source src="../static/content/tabs_scrolly.mp4" type="video/mp4"> - <source src="../static/content/tabs_scrolly.webm" type="video/webm"> - <source src="../static/content/tabs_scrolly.ogv" type="video/ogg"> - </video> - <div class="figure-caption"> - Scrolling tabs in Android Market. - <div class="video-instructions"> </div> - </div> - - </div> -</div> - - -<h2 id="fixed">Fixed Tabs</h2> - - -<p>Fixed tabs display all items concurrently. To navigate to a different view, touch the tab.</p> - -<img src="../static/content/tabs_standard.png"> -<div class="figure-caption"> - Tabs in Holo Dark & Light. -</div> - -<img src="../static/content/tabs_youtube.png"> -<div class="figure-caption"> - Tabs in the YouTube app. -</div> - - - -<h2 id="stacked">Stacked Tabs</h2> - - -<p>If view navigation is essential to your app, you can break out tabs into a separate action bar. This -permits fast view switching even on narrower screens.</p> - -<img src="../static/content/tabs_stacked.png"> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/tabs.jd b/docs/html/design/building-blocks/tabs.jd new file mode 100644 index 0000000..19ed1c3 --- /dev/null +++ b/docs/html/design/building-blocks/tabs.jd @@ -0,0 +1,59 @@ +page.title=Tabs +@jd:body + +<img src="{@docRoot}design/media/tabs_overview.png"> + +<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> + + +<h2 id="scrollable">Scrollable Tabs</h2> + + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<p>Scrolling tab controls can contain a larger number of items than a standard tab control. To navigate +to the next/previous view, swipe left or right.</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> + + +<h2 id="fixed">Fixed Tabs</h2> + + +<p>Fixed tabs display all items concurrently. To navigate to a different view, touch the tab.</p> + +<img src="{@docRoot}design/media/tabs_standard.png"> +<div class="figure-caption"> + Tabs in Holo Dark & Light. +</div> + +<img src="{@docRoot}design/media/tabs_youtube.png"> +<div class="figure-caption"> + Tabs in the YouTube app. +</div> + + + +<h2 id="stacked">Stacked Tabs</h2> + + +<p>If view navigation is essential to your app, you can break out tabs into a separate action bar. This +permits fast view switching even on narrower screens.</p> + +<img src="{@docRoot}design/media/tabs_stacked.png"> diff --git a/docs/html/design/building-blocks/text-fields.html b/docs/html/design/building-blocks/text-fields.html deleted file mode 100644 index 6496fa5..0000000 --- a/docs/html/design/building-blocks/text-fields.html +++ /dev/null @@ -1,223 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Text Fields - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Text Fields</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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, -paste) and data lookup via auto-completion.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-12"> - - <img src="../static/content/text_input_singlevsmultiline.png"> - - </div> -</div> - -<h4>Single line and multi line</h4> -<p>Single-line fields automatically scroll their content to the left as the text input cursor reaches -the right edge of the input field. Multi-line text fields automatically break to a new line for -overflow text and scroll vertically when the cursor reaches the lower edge.</p> - -<img src="../static/content/text_input_typesandtypedown.png"> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Text field types</h4> -<p>Text fields can have different types, such as number, message, or email address. The type determines -what kind of characters are allowed inside the field, and may prompt the virtual keyboard to -optimize its layout for frequently used characters.</p> - - </div> - <div class="layout-content-col span-6"> - -<h4>Auto-complete text fields</h4> -<p>Use auto-complete text fields to present real-time completions or search results in popups, so users -can enter information more accurately and efficiently.</p> - - </div> -</div> - -<h2>Text Selection</h2> - -<p>Users can select any word in a text field with a long press. This action triggers a text selection -mode that facilitates extending the selection or choosing an action to perform on the selected text. -Selection mode includes:</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-9"> - - <img src="../static/content/text_input_textselection.png"> - - </div> - <div class="layout-content-col span-4 with-callouts"> - -<ol> -<li> -<h4>Contextual action bar</h4> -<p>A contextual action bar (CAB) displays the actions available to perform on the selection: - typically cut, copy, and paste, but apps can insert additional commands as needed.</p> -</li> -<li> -<h4>Selection handles</h4> -<p>Selection handles can be dragged to select more or less text while remaining in selection mode.</p> -</li> -</ol> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/building-blocks/text-fields.jd b/docs/html/design/building-blocks/text-fields.jd new file mode 100644 index 0000000..1b10420 --- /dev/null +++ b/docs/html/design/building-blocks/text-fields.jd @@ -0,0 +1,70 @@ +page.title=Text Fields +@jd:body + +<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, +paste) and data lookup via auto-completion.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-12"> + + <img src="{@docRoot}design/media/text_input_singlevsmultiline.png"> + + </div> +</div> + +<h4>Single line and multi line</h4> +<p>Single-line fields automatically scroll their content to the left as the text input cursor reaches +the right edge of the input field. Multi-line text fields automatically break to a new line for +overflow text and scroll vertically when the cursor reaches the lower edge.</p> + +<img src="{@docRoot}design/media/text_input_typesandtypedown.png"> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Text field types</h4> +<p>Text fields can have different types, such as number, message, or email address. The type determines +what kind of characters are allowed inside the field, and may prompt the virtual keyboard to +optimize its layout for frequently used characters.</p> + + </div> + <div class="layout-content-col span-6"> + +<h4>Auto-complete text fields</h4> +<p>Use auto-complete text fields to present real-time completions or search results in popups, so users +can enter information more accurately and efficiently.</p> + + </div> +</div> + +<h2 id="text-selection">Text Selection</h2> + +<p>Users can select any word in a text field with a long press. This action triggers a text selection +mode that facilitates extending the selection or choosing an action to perform on the selected text. +Selection mode includes:</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/text_input_textselection.png"> + + </div> + <div class="layout-content-col span-4 with-callouts"> + +<ol> +<li> +<h4>Contextual action bar</h4> +<p>A contextual action bar (CAB) displays the actions available to perform on the selection: + typically cut, copy, and paste, but apps can insert additional commands as needed.</p> +</li> +<li> +<h4>Selection handles</h4> +<p>Selection handles can be dragged to select more or less text while remaining in selection mode.</p> +</li> +</ol> + + </div> +</div> diff --git a/docs/html/design/design_toc.cs b/docs/html/design/design_toc.cs new file mode 100644 index 0000000..6dd8d61 --- /dev/null +++ b/docs/html/design/design_toc.cs @@ -0,0 +1,70 @@ +<ul id="nav"> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>design/index.html">Get Started</a></div> + <ul> + <li><a href="<?cs var:toroot ?>design/get-started/creative-vision.html">Creative Vision</a></li> + <li><a href="<?cs var:toroot ?>design/get-started/principles.html">Design Principles</a></li> + <li><a href="<?cs var:toroot ?>design/get-started/ui-overview.html">UI Overview</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>design/style/index.html">Style</a></div> + <ul> + <li><a href="<?cs var:toroot ?>design/style/devices-displays.html">Devices and Displays</a></li> + <li><a href="<?cs var:toroot ?>design/style/themes.html">Themes</a></li> + <li><a href="<?cs var:toroot ?>design/style/touch-feedback.html">Touch Feedback</a></li> + <li><a href="<?cs var:toroot ?>design/style/metrics-grids.html">Metrics and Grids</a></li> + <li><a href="<?cs var:toroot ?>design/style/typography.html">Typography</a></li> + <li><a href="<?cs var:toroot ?>design/style/color.html">Color</a></li> + <li><a href="<?cs var:toroot ?>design/style/iconography.html">Iconography</a></li> + <li><a href="<?cs var:toroot ?>design/style/writing.html">Writing Style</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>design/patterns/index.html">Patterns</a></div> + <ul> + <li><a href="<?cs var:toroot ?>design/patterns/new-4-0.html">New in Android 4.0</a></li> + <li><a href="<?cs var:toroot ?>design/patterns/gestures.html">Gestures</a></li> + <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/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> + <li><a href="<?cs var:toroot ?>design/patterns/notifications.html">Notifications</a></li> + <li><a href="<?cs var:toroot ?>design/patterns/settings.html">Settings</a></li> + <li><a href="<?cs var:toroot ?>design/patterns/compatibility.html">Compatibility</a></li> + <li><a href="<?cs var:toroot ?>design/patterns/pure-android.html">Pure Android</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header"><a href="<?cs var:toroot ?>design/building-blocks/index.html">Building Blocks</a></div> + <ul> + <li><a href="<?cs var:toroot ?>design/building-blocks/tabs.html">Tabs</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/lists.html">Lists</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/grid-lists.html">Grid Lists</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/scrolling.html">Scrolling</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/spinners.html">Spinners</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/buttons.html">Buttons</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/text-fields.html">Text Fields</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/seek-bars.html">Seek Bars</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/progress.html">Progress & Activity</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/switches.html">Switches</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/dialogs.html">Dialogs</a></li> + <li><a href="<?cs var:toroot ?>design/building-blocks/pickers.html">Pickers</a></li> + </ul> + </li> + + <li class="nav-section"> + <div class="nav-section-header empty"><a href="<?cs var:toroot ?>design/downloads/index.html">Downloads</a></div> + </li> + + <li> + <div id="back-dac-section"><a href="<?cs var:toroot ?>index.html">Developers</a></div> + </li> + +</ul>
\ No newline at end of file diff --git a/docs/html/design/downloads/index.jd b/docs/html/design/downloads/index.jd new file mode 100644 index 0000000..67dfd79 --- /dev/null +++ b/docs/html/design/downloads/index.jd @@ -0,0 +1,121 @@ +page.title=Downloads +@jd:body + +<div class="layout-content-row"> + <div class="layout-content-col span-9"> + +<p>Want everything? We've bundled all the downloads available on Android Design into a single ZIP file. +You can also download individual files listed below.</p> +<p>You may use these materials without restriction in your apps and to develop your apps.</p> + + </div> + <div class="layout-content-col span-4"> + +<p> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Downloads_20120229.zip">Download All</a> +</p> + + </div> +</div> + +<h2 id="stencils">Stencils and Sources</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<p>Drag and drop your way to beautifully designed Ice Cream Sandwich apps. The stencils feature the +rich typography, colors, interactive controls, and icons found throughout Android 4.0, along with +phone and tablet outlines to frame your creations. Source files for icons and controls are also +available.</p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/downloads_stencils.png"> + + </div> + <div class="layout-content-col span-4"> + +<p> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Fireworks_Stencil_20120229.png">Adobe® Fireworks® PNG Stencil</a> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_OmniGraffle_Stencil_20120229.graffle">Omni® OmniGraffle® Stencil</a> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Holo_Widgets_20120302.zip">Adobe® Photoshop® Sources</a> +</p> + + </div> +</div> + +<h2 id="action-bar-icon-pack">Action Bar Icon Pack</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<p>Action bar icons are graphic buttons that represent the most important actions people can take +within your app. <a href="{@docRoot}design/style/iconography.html">More on Action Bar Iconography</a></p> +<p>The download package includes icons that are scaled for various screen densities and suitable for +use with the Holo Light and Holo Dark themes. The package also includes unstyled icons that you can +modify to match your theme, plus source files.</p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_actionbar_style.png"> + + </div> + <div class="layout-content-col span-4"> + +<p> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Icons_20120229.zip">Action Bar Icon Pack</a> +</p> + + </div> +</div> + +<h2 id="style">Style</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Roboto</h4> +<p>Ice Cream Sandwich introduced a new type family named Roboto, created specifically for the +requirements of UI and high-resolution screens.</p> +<p><a href="{@docRoot}design/style/typography.html#actionbar">More on Roboto</a></p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/downloads_roboto_specimen_preview.png"> + + </div> + <div class="layout-content-col span-4"> + +<p> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Roboto_Hinted_20111129.zip">Roboto</a> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Roboto_Specimen_Book_20111129.pdf">Specimen Book</a> +</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Color</h4> +<p>Blue is the standard accent color in Android's color palette. Each color has a corresponding darker +shade that can be used as a complement when needed.</p> +<p><a href="{@docRoot}design/style/color.html">More on Color</a></p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/downloads_color_swatches.png"> + + </div> + <div class="layout-content-col span-4"> + +<p> + <a class="download-button" href="https://dl-ssl.google.com/android/design/Android_Design_Color_Swatches_20120229.zip">Color Swatches</a> +</p> + + </div> +</div> diff --git a/docs/html/design/get-started/creative-vision.html b/docs/html/design/get-started/creative-vision.html deleted file mode 100644 index 11783c4..0000000 --- a/docs/html/design/get-started/creative-vision.html +++ /dev/null @@ -1,201 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Creative Vision - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Creative Vision</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<img src="../static/content/creative_vision_main.png"> - -<div class="vspace size-1"> </div> - -<p>Ice Cream Sandwich (Android 4.0) marks a major milestone for Android design. We touched nearly every -pixel of the system as we expanded the new design approaches introduced in Honeycomb tablets to all -types of mobile devices. Starting with the most basic elements, we introduced a new font, Roboto, -designed for high-resolution displays. Other big changes include framework-level action bars on -phones and support for new phones without physical buttons.</p> -<p>We focused the design work with three overarching goals for our core apps and the system at large. -As you design apps to work with Android, consider these goals:</p> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - -<h4>Enchant me</h4> -<p>Beauty is more than skin deep. Android apps are sleek and aesthetically pleasing on multiple levels. -Transitions are fast and clear; layout and typography are crisp and meaningful. App icons are works -of art in their own right. Just like a well-made tool, your app should strive to combine beauty, -simplicity and purpose to create a magical experience that is effortless and powerful.</p> - - </div> - <div class="layout-content-col span-5"> - -<h4>Simplify my life</h4> -<p>Android apps make life easier and are easy to understand. When people use your app for the first -time, they should intuitively grasp the most important features. The design work doesn't stop at the -first use, though. Android apps remove ongoing chores like file management and syncing. Simple tasks -never require complex procedures, and complex tasks are tailored to the human hand and mind. People -of all ages and cultures feel firmly in control, and are never overwhelmed by too many choices or -irrelevant flash.</p> - - </div> - <div class="layout-content-col span-4"> - -<h4>Make me amazing</h4> -<p>It's not enough to make an app that is easy to use. Android apps empower people to try new things -and to use apps in inventive new ways. Android lets people combine applications into new workflows -through multitasking, notifications, and sharing across apps. At the same time, your app should feel -personal, giving people access to superb technology with clarity and grace.</p> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/get-started/creative-vision.jd b/docs/html/design/get-started/creative-vision.jd new file mode 100644 index 0000000..792b97d --- /dev/null +++ b/docs/html/design/get-started/creative-vision.jd @@ -0,0 +1,48 @@ +page.title=Creative Vision +@jd:body + +<img src="{@docRoot}design/media/creative_vision_main.png"> + +<div class="vspace size-1"> </div> + +<p>Ice Cream Sandwich (Android 4.0) marks a major milestone for Android design. We touched nearly every +pixel of the system as we expanded the new design approaches introduced in Honeycomb tablets to all +types of mobile devices. Starting with the most basic elements, we introduced a new font, Roboto, +designed for high-resolution displays. Other big changes include framework-level action bars on +phones and support for new phones without physical buttons.</p> +<p>We focused the design work with three overarching goals for our core apps and the system at large. +As you design apps to work with Android, consider these goals:</p> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + +<h4>Enchant me</h4> +<p>Beauty is more than skin deep. Android apps are sleek and aesthetically pleasing on multiple levels. +Transitions are fast and clear; layout and typography are crisp and meaningful. App icons are works +of art in their own right. Just like a well-made tool, your app should strive to combine beauty, +simplicity and purpose to create a magical experience that is effortless and powerful.</p> + + </div> + <div class="layout-content-col span-5"> + +<h4>Simplify my life</h4> +<p>Android apps make life easier and are easy to understand. When people use your app for the first +time, they should intuitively grasp the most important features. The design work doesn't stop at the +first use, though. Android apps remove ongoing chores like file management and syncing. Simple tasks +never require complex procedures, and complex tasks are tailored to the human hand and mind. People +of all ages and cultures feel firmly in control, and are never overwhelmed by too many choices or +irrelevant flash.</p> + + </div> + <div class="layout-content-col span-4"> + +<h4>Make me amazing</h4> +<p>It's not enough to make an app that is easy to use. Android apps empower people to try new things +and to use apps in inventive new ways. Android lets people combine applications into new workflows +through multitasking, notifications, and sharing across apps. At the same time, your app should feel +personal, giving people access to superb technology with clarity and grace.</p> + + </div> +</div> diff --git a/docs/html/design/get-started/principles.html b/docs/html/design/get-started/principles.html deleted file mode 100644 index 0d9ef20..0000000 --- a/docs/html/design/get-started/principles.html +++ /dev/null @@ -1,453 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Design Principles - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Design Principles</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>These design principles were developed by and for the Android User Experience Team to keep users' -best interests in mind. Consider them as you apply your own creativity and design thinking. Deviate -with purpose.</p> - -<h2>Enchant Me</h2> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Delight me in surprising ways</h4> -<p>A beautiful surface, a carefully-placed animation, or a well-timed sound effect is a joy to -experience. Subtle effects contribute to a feeling of effortlessness and a sense that a powerful -force is at hand.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_delight.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Real objects are more fun than buttons and menus</h4> -<p>Allow people to directly touch and manipulate objects in your app. It reduces the cognitive effort -needed to perform a task while making it more emotionally satisfying.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_real_objects.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Let me make it mine</h4> -<p>People love to add personal touches because it helps them feel at home and in control. Provide -sensible, beautiful defaults, but also consider fun, optional customizations that don't hinder -primary tasks.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_make_it_mine.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Get to know me</h4> -<p>Learn peoples' preferences over time. Rather than asking them to make the same choices over and -over, place previous choices within easy reach.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_get_to_know_me.png"> - - </div> -</div> - -<h2>Simplify My Life</h2> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Keep it brief</h4> -<p>Use short phrases with simple words. People are likely to skip sentences if they're long.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_keep_it_brief.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Pictures are faster than words</h4> -<p>Consider using pictures to explain ideas. They get people's attention and can be much more efficient -than words.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_pictures.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Decide for me but let me have the final say</h4> -<p>Take your best guess and act rather than asking first. Too many choices and decisions make people -unhappy. Just in case you get it wrong, allow for 'undo'.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_decide_for_me.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Only show what I need when I need it</h4> -<p>People get overwhelmed when they see too much at once. Break tasks and information into small, -digestible chunks. Hide options that aren't essential at the moment, and teach people as they go.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_information_when_need_it.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>I should always know where I am</h4> -<p>Give people confidence that they know their way around. Make places in your app look distinct and -use transitions to show relationships among screens. Provide feedback on tasks in progress.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_navigation.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Never lose my stuff</h4> -<p>Save what people took time to create and let them access it from anywhere. Remember settings, -personal touches, and creations across phones, tablets, and computers. It makes upgrading the -easiest thing in the world.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_never_lose_stuff.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>If it looks the same, it should act the same</h4> -<p>Help people discern functional differences by making them visually distinct rather than subtle. -Avoid modes, which are places that look similar but act differently on the same input.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_looks_same.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Only interrupt me if it's important</h4> -<p>Like a good personal assistant, shield people from unimportant minutiae. People want to stay -focused, and unless it's critical and time-sensitive, an interruption can be taxing and frustrating.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_important_interruption.png"> - - </div> -</div> - -<h2>Make Me Amazing</h2> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Give me tricks that work everywhere</h4> -<p>People feel great when they figure things out for themselves. Make your app easier to learn by -leveraging visual patterns and muscle memory from other Android apps. For example, the swipe gesture -may be a good navigational shortcut.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_tricks.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>It's not my fault</h4> -<p>Be gentle in how you prompt people to make corrections. They want to feel smart when they use your -app. If something goes wrong, give clear recovery instructions but spare them the technical details. -If you can fix it behind the scenes, even better.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_error.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Sprinkle encouragement</h4> -<p>Break complex tasks into smaller steps that can be easily accomplished. Give feedback on actions, -even if it's just a subtle glow.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_sprinkle_encouragement.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Do the heavy lifting for me</h4> -<p>Make novices feel like experts by enabling them to do things they never thought they could. For -example, shortcuts that combine multiple photo effects can make amateur photographs look amazing in -only a few steps.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_heavy_lifting.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Make important things fast</h4> -<p>Not all actions are equal. Decide what's most important in your app and make it easy to find and -fast to use, like the shutter button in a camera, or the pause button in a music player.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/principles_make_important_fast.png"> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/get-started/principles.jd b/docs/html/design/get-started/principles.jd new file mode 100644 index 0000000..0b7147b --- /dev/null +++ b/docs/html/design/get-started/principles.jd @@ -0,0 +1,300 @@ +page.title=Design Principles +@jd:body + +<p>These design principles were developed by and for the Android User Experience Team to keep users' +best interests in mind. Consider them as you apply your own creativity and design thinking. Deviate +with purpose.</p> + +<h2 id="enchant-me">Enchant Me</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="delight-me">Delight me in surprising ways</h4> +<p>A beautiful surface, a carefully-placed animation, or a well-timed sound effect is a joy to +experience. Subtle effects contribute to a feeling of effortlessness and a sense that a powerful +force is at hand.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_delight.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="real-objects-more-fun">Real objects are more fun than buttons and menus</h4> +<p>Allow people to directly touch and manipulate objects in your app. It reduces the cognitive effort +needed to perform a task while making it more emotionally satisfying.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_real_objects.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="make-it-mine">Let me make it mine</h4> +<p>People love to add personal touches because it helps them feel at home and in control. Provide +sensible, beautiful defaults, but also consider fun, optional customizations that don't hinder +primary tasks.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_make_it_mine.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="get-to-know-me">Get to know me</h4> +<p>Learn peoples' preferences over time. Rather than asking them to make the same choices over and +over, place previous choices within easy reach.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_get_to_know_me.png"> + + </div> +</div> + +<h2 id="simplify-my-life">Simplify My Life</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="keep-it-brief">Keep it brief</h4> +<p>Use short phrases with simple words. People are likely to skip sentences if they're long.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_keep_it_brief.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="pictures-faster-than-words">Pictures are faster than words</h4> +<p>Consider using pictures to explain ideas. They get people's attention and can be much more efficient +than words.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_pictures.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="decide-for-me">Decide for me but let me have the final say</h4> +<p>Take your best guess and act rather than asking first. Too many choices and decisions make people +unhappy. Just in case you get it wrong, allow for 'undo'.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_decide_for_me.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="only-show-when-i-need-it">Only show what I need when I need it</h4> +<p>People get overwhelmed when they see too much at once. Break tasks and information into small, +digestible chunks. Hide options that aren't essential at the moment, and teach people as they go.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_information_when_need_it.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="always-know-where-i-am">I should always know where I am</h4> +<p>Give people confidence that they know their way around. Make places in your app look distinct and +use transitions to show relationships among screens. Provide feedback on tasks in progress.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_navigation.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="never-lose-my-stuff">Never lose my stuff</h4> +<p>Save what people took time to create and let them access it from anywhere. Remember settings, +personal touches, and creations across phones, tablets, and computers. It makes upgrading the +easiest thing in the world.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_never_lose_stuff.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="looks-same-should-act-same">If it looks the same, it should act the same</h4> +<p>Help people discern functional differences by making them visually distinct rather than subtle. +Avoid modes, which are places that look similar but act differently on the same input.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_looks_same.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="interrupt-only-if-important">Only interrupt me if it's important</h4> +<p>Like a good personal assistant, shield people from unimportant minutiae. People want to stay +focused, and unless it's critical and time-sensitive, an interruption can be taxing and frustrating.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_important_interruption.png"> + + </div> +</div> + +<h2 id="make-me-amazing">Make Me Amazing</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="give-me-tricks">Give me tricks that work everywhere</h4> +<p>People feel great when they figure things out for themselves. Make your app easier to learn by +leveraging visual patterns and muscle memory from other Android apps. For example, the swipe gesture +may be a good navigational shortcut.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_tricks.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="its-not-my-fault">It's not my fault</h4> +<p>Be gentle in how you prompt people to make corrections. They want to feel smart when they use your +app. If something goes wrong, give clear recovery instructions but spare them the technical details. +If you can fix it behind the scenes, even better.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_error.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="sprinkle-encouragement">Sprinkle encouragement</h4> +<p>Break complex tasks into smaller steps that can be easily accomplished. Give feedback on actions, +even if it's just a subtle glow.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_sprinkle_encouragement.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="do-heavy-lifting-for-me">Do the heavy lifting for me</h4> +<p>Make novices feel like experts by enabling them to do things they never thought they could. For +example, shortcuts that combine multiple photo effects can make amateur photographs look amazing in +only a few steps.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_heavy_lifting.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4 id="make-important-things-fast">Make important things fast</h4> +<p>Not all actions are equal. Decide what's most important in your app and make it easy to find and +fast to use, like the shutter button in a camera, or the pause button in a music player.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/principles_make_important_fast.png"> + + </div> +</div> diff --git a/docs/html/design/get-started/ui-overview.html b/docs/html/design/get-started/ui-overview.html deleted file mode 100644 index bd5ff9c..0000000 --- a/docs/html/design/get-started/ui-overview.html +++ /dev/null @@ -1,302 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - UI Overview - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>UI Overview</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Android's system UI provides the framework on top of which you build your app. Important aspects -include the Home screen experience, global device navigation, and notifications.</p> -<p>Your app will play an important part in keeping the overall Android experience consistent and -enjoyable to use. At the end of this chapter we introduce the main elements for achieving this goal -in your app.</p> -<p>Read on for a quick overview of the most important aspects of the Android user interface.</p> - -<h2>Home, All Apps, and Recents</h2> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/ui_overview_home_screen.png"> - -<h4>Home screen</h4> -<p>Home is a customizable space that houses app shortcuts, folders and widgets. Navigate between -different home screen panels by swiping left and right.</p> -<p>The Favorites Tray at the bottom always keeps your most important shortcuts and folders in view -regardless of which panel is currently showing.</p> -<p>Access the entire collection of apps and widgets by touching the All Apps button at the center of -the Favorites Tray.</p> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/ui_overview_all_apps.png"> - -<h4>All apps screen</h4> -<p>The All Apps screen lets you browse the entire set of apps and widgets that are installed on your -device.</p> -<p>Users can drag an app or widget icon from the All Apps screen and place it in any empty location on -any Home screen.</p> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/ui_overview_recents.png"> - -<h4>Recents screen</h4> -<p>Recents provides an efficient way of switching between recently used applications. It provides a -clear navigation path between multiple ongoing tasks.</p> -<p>The Recents button at the right side of the navigation bar displays the apps that the user has -interacted with most recently. They are organized in reverse chronological order with the most -recently used app at the bottom.</p> -<p>Switch to an app by touching it. Remove an item by swiping left or right.</p> - - </div> -</div> - -<h2>System Bars</h2> - -<p>The system bars are screen areas dedicated to the display of notifications, communication of device -status, and device navigation. Typically the system bars are displayed concurrently with your app. -Apps that display immersive content, such as movies or images, can temporarily hide the system bars -to allow the user to enjoy full screen content without distraction.</p> - -<img src="../static/content/ui_overview_system_ui.png"> - -<div class="with-callouts"> - -<ol> -<li> -<h4>Status Bar</h4> -<p>Displays pending notifications on the left and status, such as time, battery level, or signal - strength, on the right. Swipe down from the status bar to show notification details.</p> -</li> -<li> -<h4>Navigation Bar</h4> -<p>New for phones in Android 4.0, the navigation bar is present only on devices that don't have - the traditional hardware keys. It houses the device navigation controls Back, Home, and - Recents, and also displays a menu for apps written for Android 2.3 or earlier.</p> -</li> -<li> -<h4>Combined Bar</h4> -<p>On tablet form factors the status and navigation bars are combined into a single bar at the - bottom of the screen.</p> -</li> -</ol> - -</div> - -<h2>Notifications</h2> - -<p>Notifications are brief messages that users can access at any time from the status bar. They -provide updates, reminders, or information that's important, but not critical enough to warrant -interrupting the user. Open the notifications drawer by swiping down on the status bar. Touching a -notification opens the associated app. <a href="../patterns/notifications.html">More on Notifications</a></p> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/ui_overview_notifications.png"> - - </div> - <div class="layout-content-col span-9"> - - <img src="../static/content/notifications_dismiss.png"> - -<p>Most notifications have a one-line title and a one-line message. The recommended layout for a -notification includes two lines. If necessary, you can add a third line. Timestamps are optional.</p> -<p>Swiping a notification right or left removes it from the notification drawer.</p> - - </div> -</div> - - -<h2 id="app">Common App UI</h2> - - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - - <img src="../static/content/ui_overview_app_ui.png"> - - </div> - <div class="layout-content-col span-6 with-callouts"> - -<p>A typical Android app consists of action bars and the app content area.</p> -<ol> -<li> -<h4>Main Action Bar</h4> -<p>The command and control center for your app. The main action bar includes elements for - navigating your app's hierarchy and views, and also surfaces the most important actions.</p> -<p><a href="../patterns/actionbar.html">More on the Action Bar</a></p> -</li> -<li> -<h4>View Control</h4> -<p>Allows users to switch between the different views that your app provides. Views typically - consist of different arrangements of your data or different functional aspects of your app.</p> -</li> -<li> -<h4>Content Area</h4> -<p>The space where the content of your app is displayed.</p> -</li> -<li> -<h4>Split Action Bar</h4> -<p>Split action bars provide a way to distribute actions across additional bars located below - the main action bar or at the bottom of the screen. In this example, a split action bar moves - important actions that won't fit in the main bar to the bottom.</p> -</li> -</ol> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/get-started/ui-overview.jd b/docs/html/design/get-started/ui-overview.jd new file mode 100644 index 0000000..34cdd06 --- /dev/null +++ b/docs/html/design/get-started/ui-overview.jd @@ -0,0 +1,149 @@ +page.title=UI Overview +@jd:body + +<p>Android's system UI provides the framework on top of which you build your app. Important aspects +include the Home screen experience, global device navigation, and notifications.</p> +<p>Your app will play an important part in keeping the overall Android experience consistent and +enjoyable to use. At the end of this chapter we introduce the main elements for achieving this goal +in your app.</p> +<p>Read on for a quick overview of the most important aspects of the Android user interface.</p> + +<h2 id="home-all-apps-recents">Home, All Apps, and Recents</h2> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/ui_overview_home_screen.png"> + +<h4>Home screen</h4> +<p>Home is a customizable space that houses app shortcuts, folders and widgets. Navigate between +different home screen panels by swiping left and right.</p> +<p>The Favorites Tray at the bottom always keeps your most important shortcuts and folders in view +regardless of which panel is currently showing.</p> +<p>Access the entire collection of apps and widgets by touching the All Apps button at the center of +the Favorites Tray.</p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/ui_overview_all_apps.png"> + +<h4>All apps screen</h4> +<p>The All Apps screen lets you browse the entire set of apps and widgets that are installed on your +device.</p> +<p>Users can drag an app or widget icon from the All Apps screen and place it in any empty location on +any Home screen.</p> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/ui_overview_recents.png"> + +<h4>Recents screen</h4> +<p>Recents provides an efficient way of switching between recently used applications. It provides a +clear navigation path between multiple ongoing tasks.</p> +<p>The Recents button at the right side of the navigation bar displays the apps that the user has +interacted with most recently. They are organized in reverse chronological order with the most +recently used app at the bottom.</p> +<p>Switch to an app by touching it. Remove an item by swiping left or right.</p> + + </div> +</div> + +<h2 id="system-bars">System Bars</h2> + +<p>The system bars are screen areas dedicated to the display of notifications, communication of device +status, and device navigation. Typically the system bars are displayed concurrently with your app. +Apps that display immersive content, such as movies or images, can temporarily hide the system bars +to allow the user to enjoy full screen content without distraction.</p> + +<img src="{@docRoot}design/media/ui_overview_system_ui.png"> + +<div class="with-callouts"> + +<ol> +<li> +<h4>Status Bar</h4> +<p>Displays pending notifications on the left and status, such as time, battery level, or signal + strength, on the right. Swipe down from the status bar to show notification details.</p> +</li> +<li> +<h4>Navigation Bar</h4> +<p>New for phones in Android 4.0, the navigation bar is present only on devices that don't have + the traditional hardware keys. It houses the device navigation controls Back, Home, and + Recents, and also displays a menu for apps written for Android 2.3 or earlier.</p> +</li> +<li> +<h4>Combined Bar</h4> +<p>On tablet form factors the status and navigation bars are combined into a single bar at the + bottom of the screen.</p> +</li> +</ol> + +</div> + +<h2 id="notifications">Notifications</h2> + +<p>Notifications are brief messages that users can access at any time from the status bar. They +provide updates, reminders, or information that's important, but not critical enough to warrant +interrupting the user. Open the notifications drawer by swiping down on the status bar. Touching a +notification opens the associated app. <a href="{@docRoot}design/patterns/notifications.html">More on Notifications</a></p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/ui_overview_notifications.png"> + + </div> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/notifications_dismiss.png"> + +<p>Most notifications have a one-line title and a one-line message. The recommended layout for a +notification includes two lines. If necessary, you can add a third line. Timestamps are optional.</p> +<p>Swiping a notification right or left removes it from the notification drawer.</p> + + </div> +</div> + + +<h2 id="app">Common App UI</h2> + + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/ui_overview_app_ui.png"> + + </div> + <div class="layout-content-col span-6 with-callouts"> + +<p>A typical Android app consists of action bars and the app content area.</p> +<ol> +<li> +<h4>Main Action Bar</h4> +<p>The command and control center for your app. The main action bar includes elements for + navigating your app's hierarchy and views, and also surfaces the most important actions.</p> +<p><a href="{@docRoot}design/patterns/actionbar.html">More on the Action Bar</a></p> +</li> +<li> +<h4>View Control</h4> +<p>Allows users to switch between the different views that your app provides. Views typically + consist of different arrangements of your data or different functional aspects of your app.</p> +</li> +<li> +<h4>Content Area</h4> +<p>The space where the content of your app is displayed.</p> +</li> +<li> +<h4>Split Action Bar</h4> +<p>Split action bars provide a way to distribute actions across additional bars located below + the main action bar or at the bottom of the screen. In this example, a split action bar moves + important actions that won't fit in the main bar to the bottom.</p> +</li> +</ol> + + </div> +</div> diff --git a/docs/html/design/index.html b/docs/html/design/index.html deleted file mode 100644 index 14d7b63..0000000 --- a/docs/html/design/index.html +++ /dev/null @@ -1,164 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Welcome - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="static/default.css"> - -<style> -#landing-graphic-container { - position: relative; -} - -#text-overlay { - position: absolute; - left: 10px; - top: 472px; - width: 280px; -} -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="index.html">Get Started</a></div> - <ul> - <li><a href="get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="get-started/principles.html">Design Principles</a></li> - <li><a href="get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="style/index.html">Style</a></div> - <ul> - <li><a href="style/devices-displays.html">Devices and Displays</a></li> - <li><a href="style/themes.html">Themes</a></li> - <li><a href="style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="style/typography.html">Typography</a></li> - <li><a href="style/color.html">Color</a></li> - <li><a href="style/iconography.html">Iconography</a></li> - <li><a href="style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="patterns/index.html">Patterns</a></div> - <ul> - <li><a href="patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="patterns/gestures.html">Gestures</a></li> - <li><a href="patterns/app-structure.html">App Structure</a></li> - <li><a href="patterns/navigation.html">Navigation</a></li> - <li><a href="patterns/actionbar.html">Action Bar</a></li> - <li><a href="patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="patterns/selection.html">Selection</a></li> - <li><a href="patterns/notifications.html">Notifications</a></li> - <li><a href="patterns/compatibility.html">Compatibility</a></li> - <li><a href="patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="building-blocks/tabs.html">Tabs</a></li> - <li><a href="building-blocks/lists.html">Lists</a></li> - <li><a href="building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="building-blocks/spinners.html">Spinners</a></li> - <li><a href="building-blocks/buttons.html">Buttons</a></li> - <li><a href="building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="building-blocks/switches.html">Switches</a></li> - <li><a href="building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - - - - -<div id="landing-graphic-container"> - <div id="text-overlay"> - Welcome to <strong>Android Design</strong>, your place for learning how to design exceptional Android apps. - <br><br> - <a href="get-started/creative-vision.html" class="landing-page-link">Creative Vision</a> - </div> - - <a href="get-started/creative-vision.html"> - <img src="static/content/index_landing_page.png"> - </a> -</div> - - - - - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = ''; - </script> - <script src="static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/index.jd b/docs/html/design/index.jd new file mode 100644 index 0000000..d404aa6 --- /dev/null +++ b/docs/html/design/index.jd @@ -0,0 +1,29 @@ +page.title= +header.hide=1 +footer.hide=1 +@jd:body + +<style> +#landing-graphic-container { + position: relative; +} + +#text-overlay { + position: absolute; + left: 10px; + top: 472px; + width: 280px; +} +</style> + +<div id="landing-graphic-container"> + <div id="text-overlay"> + Welcome to <strong>Android Design</strong>, your place for learning how to design exceptional Android apps. + <br><br> + <a href="{@docRoot}design/get-started/creative-vision.html" class="landing-page-link">Creative Vision</a> + </div> + + <a href="{@docRoot}design/get-started/creative-vision.html"> + <img src="{@docRoot}design/media/index_landing_page.png"> + </a> +</div> diff --git a/docs/html/design/static/content/action_bar_basics.png b/docs/html/design/media/action_bar_basics.png Binary files differindex 0bf3d56..0bf3d56 100644 --- a/docs/html/design/static/content/action_bar_basics.png +++ b/docs/html/design/media/action_bar_basics.png diff --git a/docs/html/design/static/content/action_bar_cab.png b/docs/html/design/media/action_bar_cab.png Binary files differindex aa629b9..aa629b9 100644 --- a/docs/html/design/static/content/action_bar_cab.png +++ b/docs/html/design/media/action_bar_cab.png diff --git a/docs/html/design/static/content/action_bar_pattern_action_icons.png b/docs/html/design/media/action_bar_pattern_action_icons.png Binary files differindex 66f7f87..66f7f87 100644 --- a/docs/html/design/static/content/action_bar_pattern_action_icons.png +++ b/docs/html/design/media/action_bar_pattern_action_icons.png diff --git a/docs/html/design/static/content/action_bar_pattern_considerations.png b/docs/html/design/media/action_bar_pattern_considerations.png Binary files differindex 977e7f2..977e7f2 100644 --- a/docs/html/design/static/content/action_bar_pattern_considerations.png +++ b/docs/html/design/media/action_bar_pattern_considerations.png diff --git a/docs/html/design/static/content/action_bar_pattern_default_tabs.png b/docs/html/design/media/action_bar_pattern_default_tabs.png Binary files differindex 69df289..69df289 100644 --- a/docs/html/design/static/content/action_bar_pattern_default_tabs.png +++ b/docs/html/design/media/action_bar_pattern_default_tabs.png diff --git a/docs/html/design/static/content/action_bar_pattern_overflow.png b/docs/html/design/media/action_bar_pattern_overflow.png Binary files differindex 9c69cfe..9c69cfe 100644 --- a/docs/html/design/static/content/action_bar_pattern_overflow.png +++ b/docs/html/design/media/action_bar_pattern_overflow.png diff --git a/docs/html/design/static/content/action_bar_pattern_overview.png b/docs/html/design/media/action_bar_pattern_overview.png Binary files differindex 83a986b..83a986b 100644 --- a/docs/html/design/static/content/action_bar_pattern_overview.png +++ b/docs/html/design/media/action_bar_pattern_overview.png diff --git a/docs/html/design/static/content/action_bar_pattern_rotation.png b/docs/html/design/media/action_bar_pattern_rotation.png Binary files differindex 5b9a656..5b9a656 100644 --- a/docs/html/design/static/content/action_bar_pattern_rotation.png +++ b/docs/html/design/media/action_bar_pattern_rotation.png diff --git a/docs/html/design/static/content/action_bar_pattern_share_pack.png b/docs/html/design/media/action_bar_pattern_share_pack.png Binary files differindex 7ae8a0a..7ae8a0a 100644 --- a/docs/html/design/static/content/action_bar_pattern_share_pack.png +++ b/docs/html/design/media/action_bar_pattern_share_pack.png diff --git a/docs/html/design/static/content/action_bar_pattern_spinner.png b/docs/html/design/media/action_bar_pattern_spinner.png Binary files differindex 9c054b5..9c054b5 100644 --- a/docs/html/design/static/content/action_bar_pattern_spinner.png +++ b/docs/html/design/media/action_bar_pattern_spinner.png diff --git a/docs/html/design/static/content/action_bar_pattern_table.png b/docs/html/design/media/action_bar_pattern_table.png Binary files differindex dac7e21..dac7e21 100644 --- a/docs/html/design/static/content/action_bar_pattern_table.png +++ b/docs/html/design/media/action_bar_pattern_table.png diff --git a/docs/html/design/static/content/action_bar_pattern_up_app_icon.png b/docs/html/design/media/action_bar_pattern_up_app_icon.png Binary files differindex 11b8aa9..11b8aa9 100644 --- a/docs/html/design/static/content/action_bar_pattern_up_app_icon.png +++ b/docs/html/design/media/action_bar_pattern_up_app_icon.png diff --git a/docs/html/design/static/content/app_structure_book_detail_page_flip.png b/docs/html/design/media/app_structure_book_detail_page_flip.png Binary files differindex 13c9c52..13c9c52 100644 --- a/docs/html/design/static/content/app_structure_book_detail_page_flip.png +++ b/docs/html/design/media/app_structure_book_detail_page_flip.png diff --git a/docs/html/design/static/content/app_structure_fixedtabs.png b/docs/html/design/media/app_structure_fixedtabs.png Binary files differindex e41f97e..e41f97e 100644 --- a/docs/html/design/static/content/app_structure_fixedtabs.png +++ b/docs/html/design/media/app_structure_fixedtabs.png diff --git a/docs/html/design/static/content/app_structure_gallery_filmstrip.png b/docs/html/design/media/app_structure_gallery_filmstrip.png Binary files differindex deed672..deed672 100644 --- a/docs/html/design/static/content/app_structure_gallery_filmstrip.png +++ b/docs/html/design/media/app_structure_gallery_filmstrip.png diff --git a/docs/html/design/static/content/app_structure_gmail.png b/docs/html/design/media/app_structure_gmail.png Binary files differindex 862ac75..862ac75 100644 --- a/docs/html/design/static/content/app_structure_gmail.png +++ b/docs/html/design/media/app_structure_gmail.png diff --git a/docs/html/design/static/content/app_structure_gmail_swipe.png b/docs/html/design/media/app_structure_gmail_swipe.png Binary files differindex 21da4ac..21da4ac 100644 --- a/docs/html/design/static/content/app_structure_gmail_swipe.png +++ b/docs/html/design/media/app_structure_gmail_swipe.png diff --git a/docs/html/design/media/app_structure_market.png b/docs/html/design/media/app_structure_market.png Binary files differnew file mode 100644 index 0000000..5aa595e --- /dev/null +++ b/docs/html/design/media/app_structure_market.png diff --git a/docs/html/design/media/app_structure_music_lndscp.png b/docs/html/design/media/app_structure_music_lndscp.png Binary files differnew file mode 100644 index 0000000..67354de --- /dev/null +++ b/docs/html/design/media/app_structure_music_lndscp.png diff --git a/docs/html/design/static/content/app_structure_overview.png b/docs/html/design/media/app_structure_overview.png Binary files differindex 5ba25b4..5ba25b4 100644 --- a/docs/html/design/static/content/app_structure_overview.png +++ b/docs/html/design/media/app_structure_overview.png diff --git a/docs/html/design/static/content/app_structure_people_detail.png b/docs/html/design/media/app_structure_people_detail.png Binary files differindex b870796..b870796 100644 --- a/docs/html/design/static/content/app_structure_people_detail.png +++ b/docs/html/design/media/app_structure_people_detail.png diff --git a/docs/html/design/media/app_structure_scrolltabs.png b/docs/html/design/media/app_structure_scrolltabs.png Binary files differnew file mode 100644 index 0000000..ea742c2 --- /dev/null +++ b/docs/html/design/media/app_structure_scrolltabs.png diff --git a/docs/html/design/media/app_structure_shortcut_on_item.png b/docs/html/design/media/app_structure_shortcut_on_item.png Binary files differnew file mode 100644 index 0000000..1341f1f --- /dev/null +++ b/docs/html/design/media/app_structure_shortcut_on_item.png diff --git a/docs/html/design/static/content/building_blocks_landing.png b/docs/html/design/media/building_blocks_landing.png Binary files differindex 2da47b7..2da47b7 100644 --- a/docs/html/design/static/content/building_blocks_landing.png +++ b/docs/html/design/media/building_blocks_landing.png diff --git a/docs/html/design/static/content/buttons_basic.png b/docs/html/design/media/buttons_basic.png Binary files differindex 7fa3d09..7fa3d09 100644 --- a/docs/html/design/static/content/buttons_basic.png +++ b/docs/html/design/media/buttons_basic.png diff --git a/docs/html/design/static/content/buttons_borderless.png b/docs/html/design/media/buttons_borderless.png Binary files differindex 1a9d906..1a9d906 100644 --- a/docs/html/design/static/content/buttons_borderless.png +++ b/docs/html/design/media/buttons_borderless.png diff --git a/docs/html/design/static/content/buttons_default_small.png b/docs/html/design/media/buttons_default_small.png Binary files differindex 3e776ed..3e776ed 100644 --- a/docs/html/design/static/content/buttons_default_small.png +++ b/docs/html/design/media/buttons_default_small.png diff --git a/docs/html/design/static/content/color_spectrum.png b/docs/html/design/media/color_spectrum.png Binary files differindex 3fd7a57..3fd7a57 100644 --- a/docs/html/design/static/content/color_spectrum.png +++ b/docs/html/design/media/color_spectrum.png diff --git a/docs/html/design/static/content/compatibility_legacy_apps.png b/docs/html/design/media/compatibility_legacy_apps.png Binary files differindex a0400e1..a0400e1 100644 --- a/docs/html/design/static/content/compatibility_legacy_apps.png +++ b/docs/html/design/media/compatibility_legacy_apps.png diff --git a/docs/html/design/static/content/compatibility_physical_buttons.png b/docs/html/design/media/compatibility_physical_buttons.png Binary files differindex 30d5ddd..30d5ddd 100644 --- a/docs/html/design/static/content/compatibility_physical_buttons.png +++ b/docs/html/design/media/compatibility_physical_buttons.png diff --git a/docs/html/design/static/content/compatibility_virtual_nav.png b/docs/html/design/media/compatibility_virtual_nav.png Binary files differindex ea595a4..ea595a4 100644 --- a/docs/html/design/static/content/compatibility_virtual_nav.png +++ b/docs/html/design/media/compatibility_virtual_nav.png diff --git a/docs/html/design/static/content/creative_vision_main.png b/docs/html/design/media/creative_vision_main.png Binary files differindex c9d31cb..c9d31cb 100644 --- a/docs/html/design/static/content/creative_vision_main.png +++ b/docs/html/design/media/creative_vision_main.png diff --git a/docs/html/design/static/content/design_elements_landing.png b/docs/html/design/media/design_elements_landing.png Binary files differindex d078cef..d078cef 100644 --- a/docs/html/design/static/content/design_elements_landing.png +++ b/docs/html/design/media/design_elements_landing.png diff --git a/docs/html/design/static/content/devices_displays_density.png b/docs/html/design/media/devices_displays_density.png Binary files differindex a21b482..a21b482 100644 --- a/docs/html/design/static/content/devices_displays_density.png +++ b/docs/html/design/media/devices_displays_density.png diff --git a/docs/html/design/static/content/devices_displays_main.png b/docs/html/design/media/devices_displays_main.png Binary files differindex fd1c645..fd1c645 100644 --- a/docs/html/design/static/content/devices_displays_main.png +++ b/docs/html/design/media/devices_displays_main.png diff --git a/docs/html/design/static/content/dialogs_examples.png b/docs/html/design/media/dialogs_examples.png Binary files differindex 981c5f3..981c5f3 100644 --- a/docs/html/design/static/content/dialogs_examples.png +++ b/docs/html/design/media/dialogs_examples.png diff --git a/docs/html/design/static/content/dialogs_main.png b/docs/html/design/media/dialogs_main.png Binary files differindex b95266a..b95266a 100644 --- a/docs/html/design/static/content/dialogs_main.png +++ b/docs/html/design/media/dialogs_main.png diff --git a/docs/html/design/static/content/dialogs_popups_example.png b/docs/html/design/media/dialogs_popups_example.png Binary files differindex c2a66f6..c2a66f6 100644 --- a/docs/html/design/static/content/dialogs_popups_example.png +++ b/docs/html/design/media/dialogs_popups_example.png diff --git a/docs/html/design/static/content/dialogs_toasts.png b/docs/html/design/media/dialogs_toasts.png Binary files differindex cc0b815..cc0b815 100644 --- a/docs/html/design/static/content/dialogs_toasts.png +++ b/docs/html/design/media/dialogs_toasts.png diff --git a/docs/html/design/static/content/dialogs_w_no_title.png b/docs/html/design/media/dialogs_w_no_title.png Binary files differindex 47e2dbf..47e2dbf 100644 --- a/docs/html/design/static/content/dialogs_w_no_title.png +++ b/docs/html/design/media/dialogs_w_no_title.png diff --git a/docs/html/design/static/content/dialogs_w_title.png b/docs/html/design/media/dialogs_w_title.png Binary files differindex 4f2b81f..4f2b81f 100644 --- a/docs/html/design/static/content/dialogs_w_title.png +++ b/docs/html/design/media/dialogs_w_title.png diff --git a/docs/html/design/media/downloads_color_swatches.png b/docs/html/design/media/downloads_color_swatches.png Binary files differnew file mode 100644 index 0000000..af2b24f --- /dev/null +++ b/docs/html/design/media/downloads_color_swatches.png diff --git a/docs/html/design/media/downloads_roboto_specimen_preview.png b/docs/html/design/media/downloads_roboto_specimen_preview.png Binary files differnew file mode 100644 index 0000000..2954cbf --- /dev/null +++ b/docs/html/design/media/downloads_roboto_specimen_preview.png diff --git a/docs/html/design/media/downloads_stencils.png b/docs/html/design/media/downloads_stencils.png Binary files differnew file mode 100644 index 0000000..9e09319 --- /dev/null +++ b/docs/html/design/media/downloads_stencils.png diff --git a/docs/html/design/static/content/gesture_doubletouch.png b/docs/html/design/media/gesture_doubletouch.png Binary files differindex 693a593..693a593 100644 --- a/docs/html/design/static/content/gesture_doubletouch.png +++ b/docs/html/design/media/gesture_doubletouch.png diff --git a/docs/html/design/static/content/gesture_drag.png b/docs/html/design/media/gesture_drag.png Binary files differindex 6262644..6262644 100644 --- a/docs/html/design/static/content/gesture_drag.png +++ b/docs/html/design/media/gesture_drag.png diff --git a/docs/html/design/static/content/gesture_longtouch.png b/docs/html/design/media/gesture_longtouch.png Binary files differindex 3eb3cbc..3eb3cbc 100644 --- a/docs/html/design/static/content/gesture_longtouch.png +++ b/docs/html/design/media/gesture_longtouch.png diff --git a/docs/html/design/static/content/gesture_pinchclose.png b/docs/html/design/media/gesture_pinchclose.png Binary files differindex 471251f..471251f 100644 --- a/docs/html/design/static/content/gesture_pinchclose.png +++ b/docs/html/design/media/gesture_pinchclose.png diff --git a/docs/html/design/static/content/gesture_pinchopen.png b/docs/html/design/media/gesture_pinchopen.png Binary files differindex b7c3ee3..b7c3ee3 100644 --- a/docs/html/design/static/content/gesture_pinchopen.png +++ b/docs/html/design/media/gesture_pinchopen.png diff --git a/docs/html/design/static/content/gesture_swipe.png b/docs/html/design/media/gesture_swipe.png Binary files differindex f8e8a26..f8e8a26 100644 --- a/docs/html/design/static/content/gesture_swipe.png +++ b/docs/html/design/media/gesture_swipe.png diff --git a/docs/html/design/static/content/gesture_touch.png b/docs/html/design/media/gesture_touch.png Binary files differindex 5c49b17..5c49b17 100644 --- a/docs/html/design/static/content/gesture_touch.png +++ b/docs/html/design/media/gesture_touch.png diff --git a/docs/html/design/static/content/gridview_example.png b/docs/html/design/media/gridview_example.png Binary files differindex 850790f..850790f 100644 --- a/docs/html/design/static/content/gridview_example.png +++ b/docs/html/design/media/gridview_example.png diff --git a/docs/html/design/static/content/gridview_horizontal.png b/docs/html/design/media/gridview_horizontal.png Binary files differindex 1d329a1..1d329a1 100644 --- a/docs/html/design/static/content/gridview_horizontal.png +++ b/docs/html/design/media/gridview_horizontal.png diff --git a/docs/html/design/static/content/gridview_overview.png b/docs/html/design/media/gridview_overview.png Binary files differindex a831625..a831625 100644 --- a/docs/html/design/static/content/gridview_overview.png +++ b/docs/html/design/media/gridview_overview.png diff --git a/docs/html/design/static/content/gridview_style.png b/docs/html/design/media/gridview_style.png Binary files differindex 77384f9..77384f9 100644 --- a/docs/html/design/static/content/gridview_style.png +++ b/docs/html/design/media/gridview_style.png diff --git a/docs/html/design/static/content/gridview_vertical.png b/docs/html/design/media/gridview_vertical.png Binary files differindex f7d85a0..f7d85a0 100644 --- a/docs/html/design/static/content/gridview_vertical.png +++ b/docs/html/design/media/gridview_vertical.png diff --git a/docs/html/design/static/content/iconography_actionbar_colors.png b/docs/html/design/media/iconography_actionbar_colors.png Binary files differindex 2ad550a..2ad550a 100644 --- a/docs/html/design/static/content/iconography_actionbar_colors.png +++ b/docs/html/design/media/iconography_actionbar_colors.png diff --git a/docs/html/design/static/content/iconography_actionbar_focal.png b/docs/html/design/media/iconography_actionbar_focal.png Binary files differindex 49b6537..49b6537 100644 --- a/docs/html/design/static/content/iconography_actionbar_focal.png +++ b/docs/html/design/media/iconography_actionbar_focal.png diff --git a/docs/html/design/static/content/iconography_actionbar_size.png b/docs/html/design/media/iconography_actionbar_size.png Binary files differindex 307a4fe..307a4fe 100644 --- a/docs/html/design/static/content/iconography_actionbar_size.png +++ b/docs/html/design/media/iconography_actionbar_size.png diff --git a/docs/html/design/static/content/iconography_actionbar_style.png b/docs/html/design/media/iconography_actionbar_style.png Binary files differindex a48b448..a48b448 100644 --- a/docs/html/design/static/content/iconography_actionbar_style.png +++ b/docs/html/design/media/iconography_actionbar_style.png diff --git a/docs/html/design/media/iconography_launcher_example.png b/docs/html/design/media/iconography_launcher_example.png Binary files differnew file mode 100644 index 0000000..0cce7ef --- /dev/null +++ b/docs/html/design/media/iconography_launcher_example.png diff --git a/docs/html/design/static/content/iconography_launcher_example2.png b/docs/html/design/media/iconography_launcher_example2.png Binary files differindex 5a709e2..5a709e2 100644 --- a/docs/html/design/static/content/iconography_launcher_example2.png +++ b/docs/html/design/media/iconography_launcher_example2.png diff --git a/docs/html/design/static/content/iconography_launcher_focal.png b/docs/html/design/media/iconography_launcher_focal.png Binary files differindex 014a340..014a340 100644 --- a/docs/html/design/static/content/iconography_launcher_focal.png +++ b/docs/html/design/media/iconography_launcher_focal.png diff --git a/docs/html/design/static/content/iconography_launcher_size.png b/docs/html/design/media/iconography_launcher_size.png Binary files differindex 48267de..48267de 100644 --- a/docs/html/design/static/content/iconography_launcher_size.png +++ b/docs/html/design/media/iconography_launcher_size.png diff --git a/docs/html/design/static/content/iconography_launcher_style.png b/docs/html/design/media/iconography_launcher_style.png Binary files differindex b20c91b..b20c91b 100644 --- a/docs/html/design/static/content/iconography_launcher_style.png +++ b/docs/html/design/media/iconography_launcher_style.png diff --git a/docs/html/design/static/content/iconography_notification_example.png b/docs/html/design/media/iconography_notification_example.png Binary files differindex a8498ce..a8498ce 100644 --- a/docs/html/design/static/content/iconography_notification_example.png +++ b/docs/html/design/media/iconography_notification_example.png diff --git a/docs/html/design/static/content/iconography_notification_focal.png b/docs/html/design/media/iconography_notification_focal.png Binary files differindex 20d5e8f..20d5e8f 100644 --- a/docs/html/design/static/content/iconography_notification_focal.png +++ b/docs/html/design/media/iconography_notification_focal.png diff --git a/docs/html/design/static/content/iconography_notification_size.png b/docs/html/design/media/iconography_notification_size.png Binary files differindex b264e98..b264e98 100644 --- a/docs/html/design/static/content/iconography_notification_size.png +++ b/docs/html/design/media/iconography_notification_size.png diff --git a/docs/html/design/static/content/iconography_notification_style.png b/docs/html/design/media/iconography_notification_style.png Binary files differindex a52db1f..a52db1f 100644 --- a/docs/html/design/static/content/iconography_notification_style.png +++ b/docs/html/design/media/iconography_notification_style.png diff --git a/docs/html/design/media/iconography_overview.png b/docs/html/design/media/iconography_overview.png Binary files differnew file mode 100644 index 0000000..56cd409 --- /dev/null +++ b/docs/html/design/media/iconography_overview.png diff --git a/docs/html/design/static/content/iconography_small_colors.png b/docs/html/design/media/iconography_small_colors.png Binary files differindex 0ac1bfd..0ac1bfd 100644 --- a/docs/html/design/static/content/iconography_small_colors.png +++ b/docs/html/design/media/iconography_small_colors.png diff --git a/docs/html/design/static/content/iconography_small_example.png b/docs/html/design/media/iconography_small_example.png Binary files differindex 1e1400e..1e1400e 100644 --- a/docs/html/design/static/content/iconography_small_example.png +++ b/docs/html/design/media/iconography_small_example.png diff --git a/docs/html/design/static/content/iconography_small_focal.png b/docs/html/design/media/iconography_small_focal.png Binary files differindex dff3c16..dff3c16 100644 --- a/docs/html/design/static/content/iconography_small_focal.png +++ b/docs/html/design/media/iconography_small_focal.png diff --git a/docs/html/design/static/content/iconography_small_size.png b/docs/html/design/media/iconography_small_size.png Binary files differindex 748cf79..748cf79 100644 --- a/docs/html/design/static/content/iconography_small_size.png +++ b/docs/html/design/media/iconography_small_size.png diff --git a/docs/html/design/static/content/iconography_small_style.png b/docs/html/design/media/iconography_small_style.png Binary files differindex 0149ac6..0149ac6 100644 --- a/docs/html/design/static/content/iconography_small_style.png +++ b/docs/html/design/media/iconography_small_style.png diff --git a/docs/html/design/static/content/index_landing_page.png b/docs/html/design/media/index_landing_page.png Binary files differindex 3f319b0..3f319b0 100644 --- a/docs/html/design/static/content/index_landing_page.png +++ b/docs/html/design/media/index_landing_page.png diff --git a/docs/html/design/static/content/lists_main.png b/docs/html/design/media/lists_main.png Binary files differindex d89ac79..d89ac79 100644 --- a/docs/html/design/static/content/lists_main.png +++ b/docs/html/design/media/lists_main.png diff --git a/docs/html/design/static/content/metrics_48.png b/docs/html/design/media/metrics_48.png Binary files differindex 5e6c57e..5e6c57e 100644 --- a/docs/html/design/static/content/metrics_48.png +++ b/docs/html/design/media/metrics_48.png diff --git a/docs/html/design/static/content/metrics_closeup.png b/docs/html/design/media/metrics_closeup.png Binary files differindex 032115a..032115a 100644 --- a/docs/html/design/static/content/metrics_closeup.png +++ b/docs/html/design/media/metrics_closeup.png diff --git a/docs/html/design/static/content/metrics_diagram.png b/docs/html/design/media/metrics_diagram.png Binary files differindex b5e6cd2..b5e6cd2 100644 --- a/docs/html/design/static/content/metrics_diagram.png +++ b/docs/html/design/media/metrics_diagram.png diff --git a/docs/html/design/static/content/metrics_forms.png b/docs/html/design/media/metrics_forms.png Binary files differindex 449bd57..449bd57 100644 --- a/docs/html/design/static/content/metrics_forms.png +++ b/docs/html/design/media/metrics_forms.png diff --git a/docs/html/design/static/content/migrating_icons.png b/docs/html/design/media/migrating_icons.png Binary files differindex 1a25867..1a25867 100644 --- a/docs/html/design/static/content/migrating_icons.png +++ b/docs/html/design/media/migrating_icons.png diff --git a/docs/html/design/media/migrating_intents.png b/docs/html/design/media/migrating_intents.png Binary files differnew file mode 100644 index 0000000..65fc1a5 --- /dev/null +++ b/docs/html/design/media/migrating_intents.png diff --git a/docs/html/design/static/content/migrating_ios_dialers.png b/docs/html/design/media/migrating_ios_dialers.png Binary files differindex 27751d8..27751d8 100644 --- a/docs/html/design/static/content/migrating_ios_dialers.png +++ b/docs/html/design/media/migrating_ios_dialers.png diff --git a/docs/html/design/static/content/migrating_ios_galleries.png b/docs/html/design/media/migrating_ios_galleries.png Binary files differindex 04472fe..04472fe 100644 --- a/docs/html/design/static/content/migrating_ios_galleries.png +++ b/docs/html/design/media/migrating_ios_galleries.png diff --git a/docs/html/design/static/content/migrating_ios_settings.png b/docs/html/design/media/migrating_ios_settings.png Binary files differindex b17cb72..b17cb72 100644 --- a/docs/html/design/static/content/migrating_ios_settings.png +++ b/docs/html/design/media/migrating_ios_settings.png diff --git a/docs/html/design/static/content/migrating_ui_elements.png b/docs/html/design/media/migrating_ui_elements.png Binary files differindex 51c2a80..51c2a80 100644 --- a/docs/html/design/static/content/migrating_ui_elements.png +++ b/docs/html/design/media/migrating_ui_elements.png diff --git a/docs/html/design/static/content/multipane_expand.png b/docs/html/design/media/multipane_expand.png Binary files differindex bb4f371..bb4f371 100644 --- a/docs/html/design/static/content/multipane_expand.png +++ b/docs/html/design/media/multipane_expand.png diff --git a/docs/html/design/static/content/multipane_show.png b/docs/html/design/media/multipane_show.png Binary files differindex 0231adb..0231adb 100644 --- a/docs/html/design/static/content/multipane_show.png +++ b/docs/html/design/media/multipane_show.png diff --git a/docs/html/design/static/content/multipane_stack.png b/docs/html/design/media/multipane_stack.png Binary files differindex 7769f0c..7769f0c 100644 --- a/docs/html/design/static/content/multipane_stack.png +++ b/docs/html/design/media/multipane_stack.png diff --git a/docs/html/design/static/content/multipane_stretch.png b/docs/html/design/media/multipane_stretch.png Binary files differindex 5075af6..5075af6 100644 --- a/docs/html/design/static/content/multipane_stretch.png +++ b/docs/html/design/media/multipane_stretch.png diff --git a/docs/html/design/static/content/multipane_view_tablet.png b/docs/html/design/media/multipane_view_tablet.png Binary files differindex 56a6718..56a6718 100644 --- a/docs/html/design/static/content/multipane_view_tablet.png +++ b/docs/html/design/media/multipane_view_tablet.png diff --git a/docs/html/design/static/content/multipane_views.png b/docs/html/design/media/multipane_views.png Binary files differindex 9fdfcfd..9fdfcfd 100644 --- a/docs/html/design/static/content/multipane_views.png +++ b/docs/html/design/media/multipane_views.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 differnew file mode 100755 index 0000000..ded5d0a --- /dev/null +++ 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 differnew file mode 100755 index 0000000..1f5e401 --- /dev/null +++ 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 differnew file mode 100755 index 0000000..f192c88 --- /dev/null +++ b/docs/html/design/media/navigation_between_apps_up.png diff --git a/docs/html/design/static/content/navigation_between_siblings_gmail.png b/docs/html/design/media/navigation_between_siblings_gmail.png Binary files differindex fe01ed3..fe01ed3 100644 --- a/docs/html/design/static/content/navigation_between_siblings_gmail.png +++ b/docs/html/design/media/navigation_between_siblings_gmail.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 differnew file mode 100755 index 0000000..8f2b3dc --- /dev/null +++ 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 differnew file mode 100755 index 0000000..33b654c --- /dev/null +++ b/docs/html/design/media/navigation_between_siblings_market2.png diff --git a/docs/html/design/static/content/navigation_from_outside_back.png b/docs/html/design/media/navigation_from_outside_back.png Binary files differindex 971ee57..971ee57 100644 --- a/docs/html/design/static/content/navigation_from_outside_back.png +++ b/docs/html/design/media/navigation_from_outside_back.png diff --git a/docs/html/design/media/navigation_indirect_notification.png b/docs/html/design/media/navigation_indirect_notification.png Binary files differnew file mode 100644 index 0000000..6f99267 --- /dev/null +++ b/docs/html/design/media/navigation_indirect_notification.png diff --git a/docs/html/design/media/navigation_popup_notification.png b/docs/html/design/media/navigation_popup_notification.png Binary files differnew file mode 100644 index 0000000..a0a3ee7 --- /dev/null +++ b/docs/html/design/media/navigation_popup_notification.png diff --git a/docs/html/design/media/navigation_up_vs_back_gmail.png b/docs/html/design/media/navigation_up_vs_back_gmail.png Binary files differnew file mode 100644 index 0000000..ff7adfe --- /dev/null +++ b/docs/html/design/media/navigation_up_vs_back_gmail.png diff --git a/docs/html/design/media/navigation_with_back_and_up.png b/docs/html/design/media/navigation_with_back_and_up.png Binary files differnew file mode 100644 index 0000000..5440220 --- /dev/null +++ b/docs/html/design/media/navigation_with_back_and_up.png diff --git a/docs/html/design/static/content/notifications_dismiss.png b/docs/html/design/media/notifications_dismiss.png Binary files differindex 71bed4f..71bed4f 100644 --- a/docs/html/design/static/content/notifications_dismiss.png +++ b/docs/html/design/media/notifications_dismiss.png diff --git a/docs/html/design/static/content/notifications_pattern_additional_fail.png b/docs/html/design/media/notifications_pattern_additional_fail.png Binary files differindex 3945ffb..3945ffb 100644 --- a/docs/html/design/static/content/notifications_pattern_additional_fail.png +++ b/docs/html/design/media/notifications_pattern_additional_fail.png diff --git a/docs/html/design/static/content/notifications_pattern_additional_win.png b/docs/html/design/media/notifications_pattern_additional_win.png Binary files differindex 74472c3..74472c3 100644 --- a/docs/html/design/static/content/notifications_pattern_additional_win.png +++ b/docs/html/design/media/notifications_pattern_additional_win.png diff --git a/docs/html/design/static/content/notifications_pattern_anatomy.png b/docs/html/design/media/notifications_pattern_anatomy.png Binary files differindex cacc183..cacc183 100644 --- a/docs/html/design/static/content/notifications_pattern_anatomy.png +++ b/docs/html/design/media/notifications_pattern_anatomy.png diff --git a/docs/html/design/static/content/notifications_pattern_dialog_toast.png b/docs/html/design/media/notifications_pattern_dialog_toast.png Binary files differindex 517d57b..517d57b 100644 --- a/docs/html/design/static/content/notifications_pattern_dialog_toast.png +++ b/docs/html/design/media/notifications_pattern_dialog_toast.png diff --git a/docs/html/design/static/content/notifications_pattern_ongoing_music.png b/docs/html/design/media/notifications_pattern_ongoing_music.png Binary files differindex 01039bd..01039bd 100644 --- a/docs/html/design/static/content/notifications_pattern_ongoing_music.png +++ b/docs/html/design/media/notifications_pattern_ongoing_music.png diff --git a/docs/html/design/static/content/notifications_pattern_phone_icons.png b/docs/html/design/media/notifications_pattern_phone_icons.png Binary files differindex 09d8a83..09d8a83 100644 --- a/docs/html/design/static/content/notifications_pattern_phone_icons.png +++ b/docs/html/design/media/notifications_pattern_phone_icons.png diff --git a/docs/html/design/static/content/notifications_pattern_phone_ticker.png b/docs/html/design/media/notifications_pattern_phone_ticker.png Binary files differindex 601e310..601e310 100644 --- a/docs/html/design/static/content/notifications_pattern_phone_ticker.png +++ b/docs/html/design/media/notifications_pattern_phone_ticker.png diff --git a/docs/html/design/static/content/notifications_pattern_real_time_people.png b/docs/html/design/media/notifications_pattern_real_time_people.png Binary files differindex 32e62eb..32e62eb 100644 --- a/docs/html/design/static/content/notifications_pattern_real_time_people.png +++ b/docs/html/design/media/notifications_pattern_real_time_people.png diff --git a/docs/html/design/static/content/notifications_pattern_social_fail.png b/docs/html/design/media/notifications_pattern_social_fail.png Binary files differindex 2c8fddc..2c8fddc 100644 --- a/docs/html/design/static/content/notifications_pattern_social_fail.png +++ b/docs/html/design/media/notifications_pattern_social_fail.png diff --git a/docs/html/design/static/content/notifications_pattern_tablet.png b/docs/html/design/media/notifications_pattern_tablet.png Binary files differindex 15637d5..15637d5 100644 --- a/docs/html/design/static/content/notifications_pattern_tablet.png +++ b/docs/html/design/media/notifications_pattern_tablet.png diff --git a/docs/html/design/static/content/patterns_landing.png b/docs/html/design/media/patterns_landing.png Binary files differindex d9869a5..d9869a5 100644 --- a/docs/html/design/static/content/patterns_landing.png +++ b/docs/html/design/media/patterns_landing.png diff --git a/docs/html/design/static/content/picker_datetime.png b/docs/html/design/media/picker_datetime.png Binary files differindex 9876ab2..9876ab2 100644 --- a/docs/html/design/static/content/picker_datetime.png +++ b/docs/html/design/media/picker_datetime.png diff --git a/docs/html/design/static/content/picker_space.png b/docs/html/design/media/picker_space.png Binary files differindex 024776f..024776f 100644 --- a/docs/html/design/static/content/picker_space.png +++ b/docs/html/design/media/picker_space.png diff --git a/docs/html/design/static/content/principles_decide_for_me.png b/docs/html/design/media/principles_decide_for_me.png Binary files differindex 2d8b883..2d8b883 100644 --- a/docs/html/design/static/content/principles_decide_for_me.png +++ b/docs/html/design/media/principles_decide_for_me.png diff --git a/docs/html/design/static/content/principles_delight.png b/docs/html/design/media/principles_delight.png Binary files differindex 5d6e909..5d6e909 100644 --- a/docs/html/design/static/content/principles_delight.png +++ b/docs/html/design/media/principles_delight.png diff --git a/docs/html/design/static/content/principles_error.png b/docs/html/design/media/principles_error.png Binary files differindex 9376766..9376766 100644 --- a/docs/html/design/static/content/principles_error.png +++ b/docs/html/design/media/principles_error.png diff --git a/docs/html/design/static/content/principles_get_to_know_me.png b/docs/html/design/media/principles_get_to_know_me.png Binary files differindex 954363f..954363f 100644 --- a/docs/html/design/static/content/principles_get_to_know_me.png +++ b/docs/html/design/media/principles_get_to_know_me.png diff --git a/docs/html/design/static/content/principles_heavy_lifting.png b/docs/html/design/media/principles_heavy_lifting.png Binary files differindex c89c0ff..c89c0ff 100644 --- a/docs/html/design/static/content/principles_heavy_lifting.png +++ b/docs/html/design/media/principles_heavy_lifting.png diff --git a/docs/html/design/static/content/principles_important_interruption.png b/docs/html/design/media/principles_important_interruption.png Binary files differindex 0576efe..0576efe 100644 --- a/docs/html/design/static/content/principles_important_interruption.png +++ b/docs/html/design/media/principles_important_interruption.png diff --git a/docs/html/design/static/content/principles_information_when_need_it.png b/docs/html/design/media/principles_information_when_need_it.png Binary files differindex c5ef3ca..c5ef3ca 100644 --- a/docs/html/design/static/content/principles_information_when_need_it.png +++ b/docs/html/design/media/principles_information_when_need_it.png diff --git a/docs/html/design/static/content/principles_keep_it_brief.png b/docs/html/design/media/principles_keep_it_brief.png Binary files differindex 9c2813b..9c2813b 100644 --- a/docs/html/design/static/content/principles_keep_it_brief.png +++ b/docs/html/design/media/principles_keep_it_brief.png diff --git a/docs/html/design/static/content/principles_looks_same.png b/docs/html/design/media/principles_looks_same.png Binary files differindex 3a556ad..3a556ad 100644 --- a/docs/html/design/static/content/principles_looks_same.png +++ b/docs/html/design/media/principles_looks_same.png diff --git a/docs/html/design/static/content/principles_make_important_fast.png b/docs/html/design/media/principles_make_important_fast.png Binary files differindex 26da655..26da655 100644 --- a/docs/html/design/static/content/principles_make_important_fast.png +++ b/docs/html/design/media/principles_make_important_fast.png diff --git a/docs/html/design/static/content/principles_make_it_mine.png b/docs/html/design/media/principles_make_it_mine.png Binary files differindex 683a0b7..683a0b7 100644 --- a/docs/html/design/static/content/principles_make_it_mine.png +++ b/docs/html/design/media/principles_make_it_mine.png diff --git a/docs/html/design/static/content/principles_navigation.png b/docs/html/design/media/principles_navigation.png Binary files differindex c23dde7..c23dde7 100644 --- a/docs/html/design/static/content/principles_navigation.png +++ b/docs/html/design/media/principles_navigation.png diff --git a/docs/html/design/static/content/principles_never_lose_stuff.png b/docs/html/design/media/principles_never_lose_stuff.png Binary files differindex acbefea..acbefea 100644 --- a/docs/html/design/static/content/principles_never_lose_stuff.png +++ b/docs/html/design/media/principles_never_lose_stuff.png diff --git a/docs/html/design/static/content/principles_pictures.png b/docs/html/design/media/principles_pictures.png Binary files differindex cebd162..cebd162 100644 --- a/docs/html/design/static/content/principles_pictures.png +++ b/docs/html/design/media/principles_pictures.png diff --git a/docs/html/design/static/content/principles_real_objects.png b/docs/html/design/media/principles_real_objects.png Binary files differindex 3889c9a..3889c9a 100644 --- a/docs/html/design/static/content/principles_real_objects.png +++ b/docs/html/design/media/principles_real_objects.png diff --git a/docs/html/design/static/content/principles_sprinkle_encouragement.png b/docs/html/design/media/principles_sprinkle_encouragement.png Binary files differindex 8617365..8617365 100644 --- a/docs/html/design/static/content/principles_sprinkle_encouragement.png +++ b/docs/html/design/media/principles_sprinkle_encouragement.png diff --git a/docs/html/design/static/content/principles_tricks.png b/docs/html/design/media/principles_tricks.png Binary files differindex f436ce9..f436ce9 100644 --- a/docs/html/design/static/content/principles_tricks.png +++ b/docs/html/design/media/principles_tricks.png diff --git a/docs/html/design/media/progress_activity.png b/docs/html/design/media/progress_activity.png Binary files differnew file mode 100644 index 0000000..32cf1f5 --- /dev/null +++ b/docs/html/design/media/progress_activity.png diff --git a/docs/html/design/static/content/progress_activity2.png b/docs/html/design/media/progress_activity2.png Binary files differindex ec3df99..ec3df99 100644 --- a/docs/html/design/static/content/progress_activity2.png +++ b/docs/html/design/media/progress_activity2.png diff --git a/docs/html/design/media/progress_download.png b/docs/html/design/media/progress_download.png Binary files differnew file mode 100644 index 0000000..ab6bf58 --- /dev/null +++ b/docs/html/design/media/progress_download.png diff --git a/docs/html/design/static/content/progress_themes.png b/docs/html/design/media/progress_themes.png Binary files differindex df090e5..df090e5 100644 --- a/docs/html/design/static/content/progress_themes.png +++ b/docs/html/design/media/progress_themes.png diff --git a/docs/html/design/static/content/scroll_index.mp4 b/docs/html/design/media/scroll_index.mp4 Binary files differindex 383bbd8..383bbd8 100644 --- a/docs/html/design/static/content/scroll_index.mp4 +++ b/docs/html/design/media/scroll_index.mp4 diff --git a/docs/html/design/static/content/scroll_index.ogv b/docs/html/design/media/scroll_index.ogv Binary files differindex 2cd61ef..2cd61ef 100644 --- a/docs/html/design/static/content/scroll_index.ogv +++ b/docs/html/design/media/scroll_index.ogv diff --git a/docs/html/design/static/content/scroll_index.webm b/docs/html/design/media/scroll_index.webm Binary files differindex 5a665d1..5a665d1 100644 --- a/docs/html/design/static/content/scroll_index.webm +++ b/docs/html/design/media/scroll_index.webm diff --git a/docs/html/design/static/content/scroll_indicator.mp4 b/docs/html/design/media/scroll_indicator.mp4 Binary files differindex 924852e..924852e 100644 --- a/docs/html/design/static/content/scroll_indicator.mp4 +++ b/docs/html/design/media/scroll_indicator.mp4 diff --git a/docs/html/design/static/content/scroll_indicator.ogv b/docs/html/design/media/scroll_indicator.ogv Binary files differindex c037bf5..c037bf5 100644 --- a/docs/html/design/static/content/scroll_indicator.ogv +++ b/docs/html/design/media/scroll_indicator.ogv diff --git a/docs/html/design/static/content/scroll_indicator.webm b/docs/html/design/media/scroll_indicator.webm Binary files differindex 000dc0a..000dc0a 100644 --- a/docs/html/design/static/content/scroll_indicator.webm +++ b/docs/html/design/media/scroll_indicator.webm diff --git a/docs/html/design/static/content/seekbar_example.png b/docs/html/design/media/seekbar_example.png Binary files differindex 70b7e5e..70b7e5e 100644 --- a/docs/html/design/static/content/seekbar_example.png +++ b/docs/html/design/media/seekbar_example.png diff --git a/docs/html/design/static/content/seekbar_style.png b/docs/html/design/media/seekbar_style.png Binary files differindex e31445d..e31445d 100644 --- a/docs/html/design/static/content/seekbar_style.png +++ b/docs/html/design/media/seekbar_style.png diff --git a/docs/html/design/static/content/selection_adjusting_actions.png b/docs/html/design/media/selection_adjusting_actions.png Binary files differindex 0799b6b..0799b6b 100644 --- a/docs/html/design/static/content/selection_adjusting_actions.png +++ b/docs/html/design/media/selection_adjusting_actions.png diff --git a/docs/html/design/static/content/selection_cab_big.png b/docs/html/design/media/selection_cab_big.png Binary files differindex 72567cb..72567cb 100644 --- a/docs/html/design/static/content/selection_cab_big.png +++ b/docs/html/design/media/selection_cab_big.png diff --git a/docs/html/design/static/content/selection_cab_example.png b/docs/html/design/media/selection_cab_example.png Binary files differindex c49a2ad..c49a2ad 100644 --- a/docs/html/design/static/content/selection_cab_example.png +++ b/docs/html/design/media/selection_cab_example.png diff --git a/docs/html/design/static/content/selection_context_menu.png b/docs/html/design/media/selection_context_menu.png Binary files differindex c711546..c711546 100644 --- a/docs/html/design/static/content/selection_context_menu.png +++ b/docs/html/design/media/selection_context_menu.png diff --git a/docs/html/design/media/settings_checkbox.png b/docs/html/design/media/settings_checkbox.png Binary files differnew file mode 100644 index 0000000..6615bfb --- /dev/null +++ b/docs/html/design/media/settings_checkbox.png diff --git a/docs/html/design/media/settings_date_time.png b/docs/html/design/media/settings_date_time.png Binary files differnew file mode 100644 index 0000000..8df92d4 --- /dev/null +++ b/docs/html/design/media/settings_date_time.png diff --git a/docs/html/design/media/settings_dependency.png b/docs/html/design/media/settings_dependency.png Binary files differnew file mode 100644 index 0000000..4821c61 --- /dev/null +++ b/docs/html/design/media/settings_dependency.png diff --git a/docs/html/design/media/settings_flowchart.png b/docs/html/design/media/settings_flowchart.png Binary files differnew file mode 100644 index 0000000..7e8623c --- /dev/null +++ b/docs/html/design/media/settings_flowchart.png diff --git a/docs/html/design/media/settings_grouping.png b/docs/html/design/media/settings_grouping.png Binary files differnew file mode 100644 index 0000000..d271ea8 --- /dev/null +++ b/docs/html/design/media/settings_grouping.png diff --git a/docs/html/design/media/settings_individual_on_off.png b/docs/html/design/media/settings_individual_on_off.png Binary files differnew file mode 100644 index 0000000..03bea0b --- /dev/null +++ b/docs/html/design/media/settings_individual_on_off.png diff --git a/docs/html/design/media/settings_list_subscreen.png b/docs/html/design/media/settings_list_subscreen.png Binary files differnew file mode 100644 index 0000000..385aa6a --- /dev/null +++ b/docs/html/design/media/settings_list_subscreen.png diff --git a/docs/html/design/media/settings_main.png b/docs/html/design/media/settings_main.png Binary files differnew file mode 100644 index 0000000..f42a358 --- /dev/null +++ b/docs/html/design/media/settings_main.png diff --git a/docs/html/design/media/settings_master_on_off.png b/docs/html/design/media/settings_master_on_off.png Binary files differnew file mode 100644 index 0000000..e46bb97 --- /dev/null +++ b/docs/html/design/media/settings_master_on_off.png diff --git a/docs/html/design/media/settings_master_on_off_2.png b/docs/html/design/media/settings_master_on_off_2.png Binary files differnew file mode 100644 index 0000000..ab4e992 --- /dev/null +++ b/docs/html/design/media/settings_master_on_off_2.png diff --git a/docs/html/design/media/settings_multiple_choice.png b/docs/html/design/media/settings_multiple_choice.png Binary files differnew file mode 100644 index 0000000..9b28566 --- /dev/null +++ b/docs/html/design/media/settings_multiple_choice.png diff --git a/docs/html/design/media/settings_overflow.png b/docs/html/design/media/settings_overflow.png Binary files differnew file mode 100644 index 0000000..9000bec --- /dev/null +++ b/docs/html/design/media/settings_overflow.png diff --git a/docs/html/design/media/settings_slider.png b/docs/html/design/media/settings_slider.png Binary files differnew file mode 100644 index 0000000..51545c8 --- /dev/null +++ b/docs/html/design/media/settings_slider.png diff --git a/docs/html/design/media/settings_subscreen_navigation.png b/docs/html/design/media/settings_subscreen_navigation.png Binary files differnew file mode 100644 index 0000000..2ab0b96 --- /dev/null +++ b/docs/html/design/media/settings_subscreen_navigation.png diff --git a/docs/html/design/static/content/spinners_actionbar.png b/docs/html/design/media/spinners_actionbar.png Binary files differindex 5d07419..5d07419 100644 --- a/docs/html/design/static/content/spinners_actionbar.png +++ b/docs/html/design/media/spinners_actionbar.png diff --git a/docs/html/design/static/content/spinners_form.png b/docs/html/design/media/spinners_form.png Binary files differindex 79ee4e4..79ee4e4 100644 --- a/docs/html/design/static/content/spinners_form.png +++ b/docs/html/design/media/spinners_form.png diff --git a/docs/html/design/static/content/spinners_hololightanddark.png b/docs/html/design/media/spinners_hololightanddark.png Binary files differindex 9b0601e..9b0601e 100644 --- a/docs/html/design/static/content/spinners_hololightanddark.png +++ b/docs/html/design/media/spinners_hololightanddark.png diff --git a/docs/html/design/static/content/swipe_tabs.mp4 b/docs/html/design/media/swipe_tabs.mp4 Binary files differindex f8a1ab5..f8a1ab5 100644 --- a/docs/html/design/static/content/swipe_tabs.mp4 +++ b/docs/html/design/media/swipe_tabs.mp4 diff --git a/docs/html/design/static/content/swipe_tabs.ogv b/docs/html/design/media/swipe_tabs.ogv Binary files differindex ae3c86b..ae3c86b 100644 --- a/docs/html/design/static/content/swipe_tabs.ogv +++ b/docs/html/design/media/swipe_tabs.ogv diff --git a/docs/html/design/static/content/swipe_tabs.png b/docs/html/design/media/swipe_tabs.png Binary files differindex f25f061..f25f061 100644 --- a/docs/html/design/static/content/swipe_tabs.png +++ b/docs/html/design/media/swipe_tabs.png diff --git a/docs/html/design/static/content/swipe_tabs.webm b/docs/html/design/media/swipe_tabs.webm Binary files differindex 86f403e..86f403e 100644 --- a/docs/html/design/static/content/swipe_tabs.webm +++ b/docs/html/design/media/swipe_tabs.webm diff --git a/docs/html/design/static/content/swipe_views.png b/docs/html/design/media/swipe_views.png Binary files differindex 3b6ecaf..3b6ecaf 100644 --- a/docs/html/design/static/content/swipe_views.png +++ b/docs/html/design/media/swipe_views.png diff --git a/docs/html/design/static/content/swipe_views2.png b/docs/html/design/media/swipe_views2.png Binary files differindex 2ed366c..2ed366c 100644 --- a/docs/html/design/static/content/swipe_views2.png +++ b/docs/html/design/media/swipe_views2.png diff --git a/docs/html/design/static/content/switches_checkboxes.png b/docs/html/design/media/switches_checkboxes.png Binary files differindex 92b8d5c..92b8d5c 100644 --- a/docs/html/design/static/content/switches_checkboxes.png +++ b/docs/html/design/media/switches_checkboxes.png diff --git a/docs/html/design/static/content/switches_radios.png b/docs/html/design/media/switches_radios.png Binary files differindex f9bf5fc..f9bf5fc 100644 --- a/docs/html/design/static/content/switches_radios.png +++ b/docs/html/design/media/switches_radios.png diff --git a/docs/html/design/static/content/switches_switches.png b/docs/html/design/media/switches_switches.png Binary files differindex 43e2623..43e2623 100644 --- a/docs/html/design/static/content/switches_switches.png +++ b/docs/html/design/media/switches_switches.png diff --git a/docs/html/design/static/content/system_ui_landing.png b/docs/html/design/media/system_ui_landing.png Binary files differindex 1d22920..1d22920 100644 --- a/docs/html/design/static/content/system_ui_landing.png +++ b/docs/html/design/media/system_ui_landing.png diff --git a/docs/html/design/static/content/tabs_overview.png b/docs/html/design/media/tabs_overview.png Binary files differindex c336982..c336982 100644 --- a/docs/html/design/static/content/tabs_overview.png +++ b/docs/html/design/media/tabs_overview.png diff --git a/docs/html/design/media/tabs_scrolly.mp4 b/docs/html/design/media/tabs_scrolly.mp4 Binary files differnew file mode 100644 index 0000000..dc9e9c6 --- /dev/null +++ b/docs/html/design/media/tabs_scrolly.mp4 diff --git a/docs/html/design/media/tabs_scrolly.ogv b/docs/html/design/media/tabs_scrolly.ogv Binary files differnew file mode 100644 index 0000000..3e484f9 --- /dev/null +++ b/docs/html/design/media/tabs_scrolly.ogv diff --git a/docs/html/design/media/tabs_scrolly.webm b/docs/html/design/media/tabs_scrolly.webm Binary files differnew file mode 100644 index 0000000..e9d371d --- /dev/null +++ b/docs/html/design/media/tabs_scrolly.webm diff --git a/docs/html/design/static/content/tabs_stacked.png b/docs/html/design/media/tabs_stacked.png Binary files differindex 09e9958..09e9958 100644 --- a/docs/html/design/static/content/tabs_stacked.png +++ b/docs/html/design/media/tabs_stacked.png diff --git a/docs/html/design/static/content/tabs_standard.png b/docs/html/design/media/tabs_standard.png Binary files differindex 8e3ed66..8e3ed66 100644 --- a/docs/html/design/static/content/tabs_standard.png +++ b/docs/html/design/media/tabs_standard.png diff --git a/docs/html/design/static/content/tabs_youtube.png b/docs/html/design/media/tabs_youtube.png Binary files differindex 69e9268..69e9268 100644 --- a/docs/html/design/static/content/tabs_youtube.png +++ b/docs/html/design/media/tabs_youtube.png diff --git a/docs/html/design/static/content/text_input_holodarkandlight.png b/docs/html/design/media/text_input_holodarkandlight.png Binary files differindex aff61fc..aff61fc 100644 --- a/docs/html/design/static/content/text_input_holodarkandlight.png +++ b/docs/html/design/media/text_input_holodarkandlight.png diff --git a/docs/html/design/static/content/text_input_singlevsmultiline.png b/docs/html/design/media/text_input_singlevsmultiline.png Binary files differindex 7bb9a5c..7bb9a5c 100644 --- a/docs/html/design/static/content/text_input_singlevsmultiline.png +++ b/docs/html/design/media/text_input_singlevsmultiline.png diff --git a/docs/html/design/static/content/text_input_textselection.png b/docs/html/design/media/text_input_textselection.png Binary files differindex 85689cf..85689cf 100644 --- a/docs/html/design/static/content/text_input_textselection.png +++ b/docs/html/design/media/text_input_textselection.png diff --git a/docs/html/design/static/content/text_input_typesandtypedown.png b/docs/html/design/media/text_input_typesandtypedown.png Binary files differindex 32f761c..32f761c 100644 --- a/docs/html/design/static/content/text_input_typesandtypedown.png +++ b/docs/html/design/media/text_input_typesandtypedown.png diff --git a/docs/html/design/static/content/themes_holo_dark.png b/docs/html/design/media/themes_holo_dark.png Binary files differindex 916ad27..916ad27 100644 --- a/docs/html/design/static/content/themes_holo_dark.png +++ b/docs/html/design/media/themes_holo_dark.png diff --git a/docs/html/design/static/content/themes_holo_inverse.png b/docs/html/design/media/themes_holo_inverse.png Binary files differindex 72c0244..72c0244 100644 --- a/docs/html/design/static/content/themes_holo_inverse.png +++ b/docs/html/design/media/themes_holo_inverse.png diff --git a/docs/html/design/static/content/themes_holo_light.png b/docs/html/design/media/themes_holo_light.png Binary files differindex d4b0861..d4b0861 100644 --- a/docs/html/design/static/content/themes_holo_light.png +++ b/docs/html/design/media/themes_holo_light.png diff --git a/docs/html/design/static/content/touch_feedback_communication.png b/docs/html/design/media/touch_feedback_communication.png Binary files differindex bb27250..bb27250 100644 --- a/docs/html/design/static/content/touch_feedback_communication.png +++ b/docs/html/design/media/touch_feedback_communication.png diff --git a/docs/html/design/static/content/touch_feedback_manipulation.png b/docs/html/design/media/touch_feedback_manipulation.png Binary files differindex cb1f268..cb1f268 100644 --- a/docs/html/design/static/content/touch_feedback_manipulation.png +++ b/docs/html/design/media/touch_feedback_manipulation.png diff --git a/docs/html/design/static/content/touch_feedback_reaction_response.png b/docs/html/design/media/touch_feedback_reaction_response.png Binary files differindex 5a34d7a..5a34d7a 100644 --- a/docs/html/design/static/content/touch_feedback_reaction_response.png +++ b/docs/html/design/media/touch_feedback_reaction_response.png diff --git a/docs/html/design/static/content/touch_feedback_states.png b/docs/html/design/media/touch_feedback_states.png Binary files differindex 972198c..972198c 100644 --- a/docs/html/design/static/content/touch_feedback_states.png +++ b/docs/html/design/media/touch_feedback_states.png diff --git a/docs/html/design/static/content/typography_alphas.png b/docs/html/design/media/typography_alphas.png Binary files differindex 4b53bd0..4b53bd0 100644 --- a/docs/html/design/static/content/typography_alphas.png +++ b/docs/html/design/media/typography_alphas.png diff --git a/docs/html/design/static/content/typography_defaults.png b/docs/html/design/media/typography_defaults.png Binary files differindex 87f1c87..87f1c87 100644 --- a/docs/html/design/static/content/typography_defaults.png +++ b/docs/html/design/media/typography_defaults.png diff --git a/docs/html/design/static/content/typography_main.png b/docs/html/design/media/typography_main.png Binary files differindex 8298cf6..8298cf6 100644 --- a/docs/html/design/static/content/typography_main.png +++ b/docs/html/design/media/typography_main.png diff --git a/docs/html/design/static/content/typography_sizes.png b/docs/html/design/media/typography_sizes.png Binary files differindex eda1d99..eda1d99 100644 --- a/docs/html/design/static/content/typography_sizes.png +++ b/docs/html/design/media/typography_sizes.png diff --git a/docs/html/design/media/ui_overview_all_apps.png b/docs/html/design/media/ui_overview_all_apps.png Binary files differnew file mode 100644 index 0000000..17e7ece --- /dev/null +++ b/docs/html/design/media/ui_overview_all_apps.png diff --git a/docs/html/design/static/content/ui_overview_app_ui.png b/docs/html/design/media/ui_overview_app_ui.png Binary files differindex 7fc5dcd..7fc5dcd 100644 --- a/docs/html/design/static/content/ui_overview_app_ui.png +++ b/docs/html/design/media/ui_overview_app_ui.png diff --git a/docs/html/design/static/content/ui_overview_home_screen.png b/docs/html/design/media/ui_overview_home_screen.png Binary files differindex ee0e4d6..ee0e4d6 100644 --- a/docs/html/design/static/content/ui_overview_home_screen.png +++ b/docs/html/design/media/ui_overview_home_screen.png diff --git a/docs/html/design/static/content/ui_overview_notifications.png b/docs/html/design/media/ui_overview_notifications.png Binary files differindex fd7438a..fd7438a 100644 --- a/docs/html/design/static/content/ui_overview_notifications.png +++ b/docs/html/design/media/ui_overview_notifications.png diff --git a/docs/html/design/static/content/ui_overview_recents.png b/docs/html/design/media/ui_overview_recents.png Binary files differindex 4ea0583..4ea0583 100644 --- a/docs/html/design/static/content/ui_overview_recents.png +++ b/docs/html/design/media/ui_overview_recents.png diff --git a/docs/html/design/static/content/ui_overview_system_ui.png b/docs/html/design/media/ui_overview_system_ui.png Binary files differindex ecc4b7d..ecc4b7d 100644 --- a/docs/html/design/static/content/ui_overview_system_ui.png +++ b/docs/html/design/media/ui_overview_system_ui.png diff --git a/docs/html/design/static/content/whats_new_action_bar.png b/docs/html/design/media/whats_new_action_bar.png Binary files differindex 713187e..713187e 100644 --- a/docs/html/design/static/content/whats_new_action_bar.png +++ b/docs/html/design/media/whats_new_action_bar.png diff --git a/docs/html/design/static/content/whats_new_multipanel.png b/docs/html/design/media/whats_new_multipanel.png Binary files differindex 8e9c2f0..8e9c2f0 100644 --- a/docs/html/design/static/content/whats_new_multipanel.png +++ b/docs/html/design/media/whats_new_multipanel.png diff --git a/docs/html/design/static/content/whats_new_multiselect.png b/docs/html/design/media/whats_new_multiselect.png Binary files differindex ab34b24..ab34b24 100644 --- a/docs/html/design/static/content/whats_new_multiselect.png +++ b/docs/html/design/media/whats_new_multiselect.png diff --git a/docs/html/design/static/content/whats_new_nav_bar.png b/docs/html/design/media/whats_new_nav_bar.png Binary files differindex 46239e5..46239e5 100644 --- a/docs/html/design/static/content/whats_new_nav_bar.png +++ b/docs/html/design/media/whats_new_nav_bar.png diff --git a/docs/html/design/patterns/actionbar.html b/docs/html/design/patterns/actionbar.jd index 911c549..2226fec 100644 --- a/docs/html/design/patterns/actionbar.html +++ b/docs/html/design/patterns/actionbar.jd @@ -1,108 +1,7 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Action Bar - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Action Bar</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<img src="../static/content/action_bar_pattern_overview.png"> +page.title=Action Bar +@jd:body + +<img src="{@docRoot}design/media/action_bar_pattern_overview.png"> <p>The <em>action bar</em> is arguably the most important structural element of an Android app. It's a dedicated piece of real estate at the top of each screen that is generally persistent throughout the @@ -118,9 +17,10 @@ app.</p> <p>If you're new to writing Android apps, note that the action bar is one of the most important design elements you can implement. Following the guidelines described here will go a long way toward making your app's interface consistent with the core Android apps.</p> -<h2>General Organization</h2> +<h2 id="organization">General Organization</h2> + <p>The action bar is split into four different functional areas that apply to most apps.</p> -<img src="../static/content/action_bar_basics.png"> +<img src="{@docRoot}design/media/action_bar_basics.png"> <div class="layout-content-row"> <div class="layout-content-col span-7 with-callouts"> @@ -129,14 +29,14 @@ your app's interface consistent with the core Android apps.</p> <li class="value-1"><h4>App icon</h4> <p> -The app icon establishes your app's identity. It can be replaced with a different logo or branding if -you wish. +The app icon establishes your app's identity. It can be replaced with a different logo or branding +if you wish. Important: If the app is currently not displaying the top-level screen, be sure to display the Up caret to the left of the app icon, so the user can navigate up the hierarchy. For more discussion of -Up navigation, see the <a href="../patterns/navigation.html">Navigation</a> pattern. +Up navigation, see the <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> pattern. <div class="figure"> - <img src="../static/content/action_bar_pattern_up_app_icon.png"> + <img src="{@docRoot}design/media/action_bar_pattern_up_app_icon.png"> <div class="figure-caption"> App icon with and without "up" affordance. </div> @@ -180,23 +80,22 @@ Move less often used actions to the action overflow. </p> </li> </ol> - </div> </div> +<h2 id="adapting-rotation">Adapting to Rotation and Different Screen Sizes</h2> -<h2>Adapting to Rotation and Different Screen Sizes</h2> <p>One of the most important UI issues to consider when creating an app is how to adjust to screen rotation on different screen sizes.</p> <p>You can adapt to such changes by using <em>split action bars</em>, which allow you to distribute action bar content across multiple bars located below the main action bar or at the bottom of the screen.</p> -<img src="../static/content/action_bar_pattern_rotation.png"> +<img src="{@docRoot}design/media/action_bar_pattern_rotation.png"> <div class="figure-caption"> Split action bar showing action buttons at the bottom of the screen in vertical orientation. </div> -<h2>Layout Considerations for Split Action Bars</h2> +<h2 id="considerations-split-action-bars">Layout Considerations for Split Action Bars</h2> <div class="layout-content-row"> <div class="layout-content-col span-8 with-callouts"> @@ -217,17 +116,18 @@ the top bar.</p> </div> <div class="layout-content-col span-3"> - <img src="../static/content/action_bar_pattern_considerations.png"> + <img src="{@docRoot}design/media/action_bar_pattern_considerations.png"> </div> </div> -<h2>Contextual Action Bars</h2> +<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="../static/content/action_bar_cab.png"> +<img src="{@docRoot}design/media/action_bar_cab.png"> <div class="figure-caption"> Contextual action bar shown in Browser and Gmail </div> @@ -244,12 +144,13 @@ selected data or text.</p> <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 "Selection" pattern.</p> -<h2>Action Bar Elements</h2> +<h2 id="elements">Action Bar Elements</h2> + <h4>Tabs</h4> <p><em>Tabs</em> display app views concurrently and make it easy to explore and switch between them. Use tabs if you expect your users to switch views frequently.</p> -<img src="../static/content/tabs_youtube.png"> +<img src="{@docRoot}design/media/tabs_youtube.png"> <p>There are two types of tabs: fixed and scrollable.</p> @@ -270,12 +171,12 @@ themselves.</p> <div class="layout-content-col span-7"> <video width="400" class="with-shadow play-on-hover" autoplay> - <source src="../static/content/tabs_scrolly.mp4" type="video/mp4"> - <source src="../static/content/tabs_scrolly.webm" type="video/webm"> - <source src="../static/content/tabs_scrolly.ogv" type="video/ogg"> + <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 Android Market. + Scrolling tabs in the Play Store app. <div class="video-instructions"> </div> </div> @@ -292,7 +193,7 @@ tabs. Fixed tabs in the main action bar can move to the top bar when the screen </div> <div class="layout-content-col span-7"> - <img src="../static/content/action_bar_pattern_default_tabs.png"> + <img src="{@docRoot}design/media/action_bar_pattern_default_tabs.png"> <div class="figure-caption"> Default fixed tabs shown in Holo Dark & Light. </div> @@ -314,7 +215,7 @@ tabs. Fixed tabs in the main action bar can move to the top bar when the screen </div> <div class="layout-content-col span-7"> - <img src="../static/content/action_bar_pattern_spinner.png"> + <img src="{@docRoot}design/media/action_bar_pattern_spinner.png"> <div class="figure-caption"> Action bar spinner from Calendar application. </div> @@ -326,9 +227,11 @@ tabs. Fixed tabs in the main action bar can move to the top bar when the screen <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.</p> +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> -<img src="../static/content/action_bar_pattern_action_icons.png"> +<img src="{@docRoot}design/media/action_bar_pattern_action_icons.png"> <div class="figure-caption"> A sampling of action buttons used throughout the Gmail application. </div> @@ -380,8 +283,7 @@ files for further customization. </p> <p> -<a href="../static/download/action_bar_icons-v4.0.zip">Download the Action Bar Icon -Pack</a> +<a href="https://dl-ssl.google.com/android/design/Android_Design_Icons_20120229.zip">Download the Action Bar Icon Pack</a> </p> @@ -396,7 +298,7 @@ display the action overflow when the user presses the key.</p> </div> <div class="layout-content-col span-7"> - <img src="../static/content/action_bar_pattern_overflow.png"> + <img src="{@docRoot}design/media/action_bar_pattern_overflow.png"> <div class="figure-caption"> Action overflow is pinned to the right side. </div> @@ -420,7 +322,7 @@ rules:</p> </li> </ul> -<img src="../static/content/action_bar_pattern_table.png"> +<img src="{@docRoot}design/media/action_bar_pattern_table.png"> <div class="figure-caption"> In the above table "o" denotes an action bar item and "=" an overflow icon. </div> @@ -431,12 +333,13 @@ provider</em> in your action bar. The share action provider is designed to speed displaying the most recently used sharing service next to a spinner button that contains other sharing options.</p> -<img src="../static/content/action_bar_pattern_share_pack.png"> +<img src="{@docRoot}design/media/action_bar_pattern_share_pack.png"> <div class="figure-caption"> The Gallery app's share action provider with extended spinner for additional sharing options. </div> -<h2>Action Bar Checklist</h2> +<h2 id="checklist">Action Bar Checklist</h2> + <p>When planning your split action bars, ask yourself questions like these:</p> <h4>How important is view navigation to the task?</h4> <p>If view navigation is very important to your app, use tabs (for fastest view-switching) or spinners.</p> @@ -449,55 +352,3 @@ actions exceeds the capacity of the main action bar, display them separately in 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> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/app-structure.html b/docs/html/design/patterns/app-structure.jd index fb9205b..e2398ed 100644 --- a/docs/html/design/patterns/app-structure.html +++ b/docs/html/design/patterns/app-structure.jd @@ -1,106 +1,5 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Application Structure - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Application Structure</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - +page.title=Application Structure +@jd:body <p>Apps come in many varieties that address very different needs. For example:</p> <ul> @@ -108,17 +7,18 @@ Android Design - Application Structure single screen</li> <li>Apps such as Phone whose main purpose is to switch between different activities without deeper navigation</li> -<li>Apps such as Gmail or Market that combine a broad set of data views with deep navigation</li> +<li>Apps such as Gmail or the Play Store that combine a broad set of data views with deep navigation</li> </ul> <p>Your app's structure depends largely on the content and tasks you want to surface for your users.</p> -<h2>General Structure</h2> +<h2 id="general-structure">General Structure</h2> + <p>A typical Android app consists of top level and detail/edit views. If the navigation hierarchy is deep and complex, category views connect top level and detail views.</p> <div class="layout-content-row"> <div class="layout-content-col span-9"> - <img src="../static/content/app_structure_overview.png"> + <img src="{@docRoot}design/media/app_structure_overview.png"> </div> <div class="layout-content-col span-4"> @@ -139,7 +39,8 @@ facet of your app.</p> </div> </div> -<h2>Top Level</h2> +<h2 id="top-level">Top Level</h2> + <p>The layout of your start screen requires special attention. This is the first screen people see after launching your app, so it should be an equally rewarding experience for new and frequent visitors alike.</p> @@ -157,9 +58,9 @@ layouts that are visually engaging and appropriate for the data type and screen </div> <div class="layout-content-col span-8"> - <img src="../static/content/app_structure_market.png"> + <img src="{@docRoot}design/media/app_structure_market.png"> <div class="figure-caption"> - Market's start screen primarily allows navigation into the stores for Apps, Music, Books, + 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 surface content of interest to the user. Search is readily available from the action bar. </div> @@ -188,7 +89,7 @@ important actions.</p> </div> <div class="layout-content-col span-8"> - <img src="../static/content/app_structure_gmail.png"> + <img src="{@docRoot}design/media/app_structure_gmail.png"> <div class="figure-caption"> Email is about productivity, so an efficient, easy-to-skim list with higher data density works well. Navigation supports switching between accounts and recent labels. Icons for creating a @@ -210,7 +111,7 @@ monotony of simple list views.</p> </div> <div class="layout-content-col span-8"> - <img src="../static/content/app_structure_music_lndscp.png"> + <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. @@ -219,7 +120,8 @@ monotony of simple list views.</p> </div> </div> -<h2>Categories</h2> +<h2 id="categories">Categories</h2> + <p>Generally, the purpose of a deep, data-driven app is to navigate through organizational categories to the detail level, where data can be viewed and managed. Minimize perceived navigation effort by keeping your apps shallow.</p> @@ -241,10 +143,10 @@ experience than to an explicit navigation step.</p> items are in view simultaneously). Keep the number of scrolling tabs at a manageable level to minimize navigational effort. Rule of thumb: no more than 5–7 tabs.</p> - <img src="../static/content/app_structure_scrolltabs.png"> + <img src="{@docRoot}design/media/app_structure_scrolltabs.png"> <div class="figure-caption"> - Market uses tabs to simultaneously show category choice and content. To navigate between - categories, users can swipe left/right on the content. + The Play Store app uses tabs to simultaneously show category choice and content. To navigate + between categories, users can swipe left/right on the content. </div> </div> @@ -253,7 +155,7 @@ minimize navigational effort. Rule of thumb: no more than 5–7 tabs.</p> <p>If the categories in the tabs are not closely related, favor fixed tabs, so that all categories are in view at the same time.</p> - <img src="../static/content/app_structure_fixedtabs.png"> + <img src="{@docRoot}design/media/app_structure_fixedtabs.png"> <div class="figure-caption"> YouTube uses fixed tabs to switch between different, relatively unrelated functional areas. </div> @@ -268,7 +170,7 @@ invocation of actions for a data item from within list or grid views, display pr directly on list view items using drop-downs or split list items. This lets people invoke actions on data without having to navigate all the way down the hierarchy.</p> -<img src="../static/content/app_structure_shortcut_on_item.png"> +<img src="{@docRoot}design/media/app_structure_shortcut_on_item.png"> <div class="figure-caption"> Music allows the user to act upon a data item (song) from within the category view (album), thereby removing the need to navigate all the way down to the song's detail view. @@ -281,7 +183,8 @@ are often good reasons to act on collections of data as well.</p> delete multiple items in the category view. Analyze which detail view actions are applicable to collections of items. Then use multi-select to allow application of those actions to multiple items in a category view.</p> -<h2>Details</h2> +<h2 id="details">Details</h2> + <p>The detail view allows you to view and act on your data. The layout of the detail view depends on the data type being displayed, and therefore differs widely among apps.</p> @@ -293,12 +196,12 @@ the data type being displayed, and therefore differs widely among apps.</p> For immersive content, make use of the lights-out mode to allow for distraction-free viewing of full-screen content.</p> - <img src="../static/content/app_structure_people_detail.png"> + <img src="{@docRoot}design/media/app_structure_people_detail.png"> </div> <div class="layout-content-col span-9"> - <img src="../static/content/app_structure_book_detail_page_flip.png"> + <img src="{@docRoot}design/media/app_structure_book_detail_page_flip.png"> <div class="figure-caption"> Google Books' detail view is all about replicating the experience of reading an actual book. The page-flip animation reinforces that notion. To create an immersive experience the app @@ -319,18 +222,19 @@ full-screen content.</p> between items from within the detail view. Use swipe views or other techniques, such as filmstrips, to achieve this.</p> -<img src="../static/content/app_structure_gmail_swipe.png"> +<img src="{@docRoot}design/media/app_structure_gmail_swipe.png"> <div class="figure-caption"> Gmail using swipe views to navigate from detail view to detail view. </div> -<img src="../static/content/app_structure_gallery_filmstrip.png"> +<img src="{@docRoot}design/media/app_structure_gallery_filmstrip.png"> <div class="figure-caption"> In addition to supporting swipe gestures to move left or right through images, Gallery provides a filmstrip control that lets people quickly jump to specific images. </div> -<h2>Checklist</h2> +<h2 id="checklist">Checklist</h2> + <ul> <li> <p>Find ways to display useful content on your start screen.</p> @@ -348,55 +252,3 @@ to achieve this.</p> <p>Allow for quick navigation between detail items with swipe views.</p> </li> </ul> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/compatibility.html b/docs/html/design/patterns/compatibility.html deleted file mode 100644 index f18c62d..0000000 --- a/docs/html/design/patterns/compatibility.html +++ /dev/null @@ -1,214 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Backwards Compatibility - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Backwards Compatibility</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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 - via virtual controls (Back, Home, Recents).</li> -<li>Robust pattern for the use of menus in action bars.</li> -</ul> -<p>Android 4.0 brings these changes for tablets to the phone platform.</p> - -<h2>Adapting Android 4.0 to Older Hardware and Apps</h2> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Phones with virtual navigation controls</h4> -<p>Android apps written for Android 3.0 and later display actions in the action bar. Actions that don't -fit in the action bar or aren't important enough to be displayed at the top level appear in the -action overflow.</p> -<p>Users access the action overflow by touching it in the action bar.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/compatibility_virtual_nav.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Phones with physical navigation keys</h4> -<p>Android phones with traditional navigation hardware keys don't display the virtual navigation bar at -the bottom of the screen. Instead, the action overflow is available from the menu hardware key. The -resulting actions popup has the same style as in the previous example, but is displayed at the bottom of the screen.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/compatibility_physical_buttons.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Legacy apps on phones with virtual navigation controls</h4> -<p>When you run an app that was built for Android 2.3 or earlier on a phone with virtual navigation -controls, an action overflow control appears at the right side of the virtual navigation bar. You -can touch the control to display the app's actions in the traditional Android menu styling.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/compatibility_legacy_apps.png"> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/compatibility.jd b/docs/html/design/patterns/compatibility.jd new file mode 100644 index 0000000..84ae337 --- /dev/null +++ b/docs/html/design/patterns/compatibility.jd @@ -0,0 +1,61 @@ +page.title=Backwards Compatibility +@jd:body + +<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 + via virtual controls (Back, Home, Recents).</li> +<li>Robust pattern for the use of menus in action bars.</li> +</ul> +<p>Android 4.0 brings these changes for tablets to the phone platform.</p> + +<h2 id="older-hardware">Adapting Android 4.0 to Older Hardware and Apps</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Phones with virtual navigation controls</h4> +<p>Android apps written for Android 3.0 and later display actions in the action bar. Actions that don't +fit in the action bar or aren't important enough to be displayed at the top level appear in the +action overflow.</p> +<p>Users access the action overflow by touching it in the action bar.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/compatibility_virtual_nav.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Phones with physical navigation keys</h4> +<p>Android phones with traditional navigation hardware keys don't display the virtual navigation bar at +the bottom of the screen. Instead, the action overflow is available from the menu hardware key. The +resulting actions popup has the same style as in the previous example, but is displayed at the bottom of the screen.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/compatibility_physical_buttons.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Legacy apps on phones with virtual navigation controls</h4> +<p>When you run an app that was built for Android 2.3 or earlier on a phone with virtual navigation +controls, an action overflow control appears at the right side of the virtual navigation bar. You +can touch the control to display the app's actions in the traditional Android menu styling.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/compatibility_legacy_apps.png"> + + </div> +</div> diff --git a/docs/html/design/patterns/gestures.html b/docs/html/design/patterns/gestures.html deleted file mode 100644 index f8585e4..0000000 --- a/docs/html/design/patterns/gestures.html +++ /dev/null @@ -1,268 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Gestures - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Gestures</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Gestures allow users to interact with your app by manipulating the screen objects you provide. The -following table shows the core gesture set that is supported in Android.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_touch.png"> - -<h4>Touch</h4> -<p>Triggers the default functionality for a given item.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>Press, lift</p></li> -</ul> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_longtouch.png"> - -<h4>Long press</h4> -<p>Enters data selection mode. Allows you to select one or more items in a view and act upon - the data using a contextual action bar. Avoid using long press for showing contextual menus.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>Press, wait, lift</p></li> -</ul> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_swipe.png"> - -<h4>Swipe</h4> -<p>Scrolls overflowing content, or navigates between views in the same hierarchy.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>Press, move, lift</p></li> -</ul> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_drag.png"> - -<h4>Drag</h4> -<p>Rearranges data within a view, or moves data into a container (e.g. folders on Home Screen).</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>Long press, move, lift</p></li> -</ul> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_doubletouch.png"> - -<h4>Double touch</h4> -<p>Zooms into content. Also used as a secondary gesture for text selection.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>Two touches in quick succession</p></li> -</ul> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_pinchopen.png"> - -<h4>Pinch open</h4> -<p>Zooms into content.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>2-finger press, move outwards, lift</p></li> -</ul> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/gesture_pinchclose.png"> - -<h4>Pinch close</h4> -<p>Zooms out of content.</p> - -<ul> - <li class="no-bullet with-icon action"> - <h4>Action</h4> - <p>2-finger press, move inwards, lift</p></li> -</ul> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/gestures.jd b/docs/html/design/patterns/gestures.jd new file mode 100644 index 0000000..9868df2 --- /dev/null +++ b/docs/html/design/patterns/gestures.jd @@ -0,0 +1,115 @@ +page.title=Gestures +@jd:body + +<p>Gestures allow users to interact with your app by manipulating the screen objects you provide. The +following table shows the core gesture set that is supported in Android.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_touch.png"> + +<h4>Touch</h4> +<p>Triggers the default functionality for a given item.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>Press, lift</p></li> +</ul> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_longtouch.png"> + +<h4>Long press</h4> +<p>Enters data selection mode. Allows you to select one or more items in a view and act upon + the data using a contextual action bar. Avoid using long press for showing contextual menus.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>Press, wait, lift</p></li> +</ul> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_swipe.png"> + +<h4>Swipe</h4> +<p>Scrolls overflowing content, or navigates between views in the same hierarchy.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>Press, move, lift</p></li> +</ul> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_drag.png"> + +<h4>Drag</h4> +<p>Rearranges data within a view, or moves data into a container (e.g. folders on Home Screen).</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>Long press, move, lift</p></li> +</ul> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_doubletouch.png"> + +<h4>Double touch</h4> +<p>Zooms into content. Also used as a secondary gesture for text selection.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>Two touches in quick succession</p></li> +</ul> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_pinchopen.png"> + +<h4>Pinch open</h4> +<p>Zooms into content.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>2-finger press, move outwards, lift</p></li> +</ul> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/gesture_pinchclose.png"> + +<h4>Pinch close</h4> +<p>Zooms out of content.</p> + +<ul> + <li class="no-bullet with-icon action"> + <h4>Action</h4> + <p>2-finger press, move inwards, lift</p></li> +</ul> + + </div> +</div> diff --git a/docs/html/design/patterns/index.html b/docs/html/design/patterns/index.html deleted file mode 100644 index ff797db..0000000 --- a/docs/html/design/patterns/index.html +++ /dev/null @@ -1,171 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Design Patterns - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - -<style> -#landing-graphic-container { - position: relative; -} - -#text-overlay { - position: absolute; - left: 10px; - top: 492px; - width: 200px; -} -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - -<div class="layout-content-row content-header just-links"> - <div class="layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> -</div> - - - - -<div id="landing-graphic-container"> - <div id="text-overlay"> - Design apps that behave in a consistent, predictable fashion. - <br><br> - <a href="../patterns/new-4-0.html" class="landing-page-link">New in Android 4.0</a> - </div> - - <a href="../patterns/new-4-0.html"> - <img src="../static/content/patterns_landing.png"> - </a> -</div> - - - - - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/index.jd b/docs/html/design/patterns/index.jd new file mode 100644 index 0000000..732e4db --- /dev/null +++ b/docs/html/design/patterns/index.jd @@ -0,0 +1,29 @@ +page.title=Patterns +header.justLinks=1 +footer.hide=1 +@jd:body + +<style> +#landing-graphic-container { + position: relative; +} + +#text-overlay { + position: absolute; + left: 10px; + top: 492px; + width: 200px; +} +</style> + +<div id="landing-graphic-container"> + <div id="text-overlay"> + Design apps that behave in a consistent, predictable fashion. + <br><br> + <a href="{@docRoot}design/patterns/new-4-0.html" class="landing-page-link">New in Android 4.0</a> + </div> + + <a href="{@docRoot}design/patterns/new-4-0.html"> + <img src="{@docRoot}design/media/patterns_landing.png"> + </a> +</div> diff --git a/docs/html/design/patterns/multi-pane-layouts.html b/docs/html/design/patterns/multi-pane-layouts.html deleted file mode 100644 index af05e31..0000000 --- a/docs/html/design/patterns/multi-pane-layouts.html +++ /dev/null @@ -1,260 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Multi-pane Layouts - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Multi-pane Layouts</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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> -<p><em>Panels</em> are a great way for your app to achieve this. They allow you to combine multiple views into -one compound view when a lot of horizontal screen real estate is available and by splitting them up -when less space is available.</p> -<h2>Combining Multiple Views Into One</h2> -<p>On smaller devices your content is typically divided into a master grid or list view and a detail -view. Touching an item in the master view opens a different screen showing that item's detail -information.</p> - -<img src="../static/content/multipane_views.png"> - -<p>Because tablets have more screen real estate than phones, you can use panels to combine the related -list and detail views into a single compound view. This uses the additional space more efficiently -and makes navigating the app easier. </p> - -<img src="../static/content/multipane_view_tablet.png"> - -<p>In general, use the pane on the right to present more information about the item you selected in the -left pane. Make sure to keep the item in the left pane selected in order to establish the -relationship between the panels.</p> -<h2>Compound Views and Orientation Changes</h2> -<p>Screens should have the same functionality regardless of orientation. If you use a compound view in -one orientation, don't split it up when the user rotates the screen. There are several techniques -you can use to adjust the layout after orientation change while keeping functional parity intact.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/multipane_stretch.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Stretch/compress</h4> -<p>Adjust the column width of your left pane to achieve a balanced layout in both orientations.</p> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/multipane_stack.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Stack</h4> -<p>Rearrange the panels on your screen to match the orientation.</p> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/multipane_expand.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Expand/collapse</h4> -<p>When the device rotates, collapse the left pane view to only show the most important information. -Provide an <em>expand</em> control that allows the user to bring the left pane content back to its original -width and vice versa.</p> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/multipane_show.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Show/hide</h4> -<p>After rotating the device, show the right pane in fullscreen view. Use the Up icon in the action bar -to show the left panel and allow navigation to a different email. Hide the left panel by touching -the content in the detail panel.</p> - - </div> -</div> - -<h2>Checklist</h2> -<ul> -<li> -<p>Plan in advance on how your app scales to different screen sizes and screen orientations.</p> -</li> -<li> -<p>Identify the most appropriate method for the panels in your compound views to reorganize - themselves when screen orientation changes.</p> -</li> -<li> -<p>Look for opportunities to consolidate your views into multi-panel compound views.</p> -</li> -<li> -<p>Make sure that your screens provide functional parity after the screen orientation - changes.</p> -</li> -</ul> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/multi-pane-layouts.jd b/docs/html/design/patterns/multi-pane-layouts.jd new file mode 100644 index 0000000..0e63e32 --- /dev/null +++ b/docs/html/design/patterns/multi-pane-layouts.jd @@ -0,0 +1,110 @@ +page.title=Multi-pane Layouts +@jd:body + +<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> +<p><em>Panels</em> are a great way for your app to achieve this. They allow you to combine multiple views into +one compound view when a lot of horizontal screen real estate is available and by splitting them up +when less space is available.</p> +<h2 id="combining-views">Combining Multiple Views Into One</h2> + +<p>On smaller devices your content is typically divided into a master grid or list view and a detail +view. Touching an item in the master view opens a different screen showing that item's detail +information.</p> + +<img src="{@docRoot}design/media/multipane_views.png"> + +<p>Because tablets have more screen real estate than phones, you can use panels to combine the related +list and detail views into a single compound view. This uses the additional space more efficiently +and makes navigating the app easier. </p> + +<img src="{@docRoot}design/media/multipane_view_tablet.png"> + +<p>In general, use the pane on the right to present more information about the item you selected in the +left pane. Make sure to keep the item in the left pane selected in order to establish the +relationship between the panels.</p> +<h2 id="orientation">Compound Views and Orientation Changes</h2> + +<p>Screens should have the same functionality regardless of orientation. If you use a compound view in +one orientation, don't split it up when the user rotates the screen. There are several techniques +you can use to adjust the layout after orientation change while keeping functional parity intact.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/multipane_stretch.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Stretch/compress</h4> +<p>Adjust the column width of your left pane to achieve a balanced layout in both orientations.</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/multipane_stack.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Stack</h4> +<p>Rearrange the panels on your screen to match the orientation.</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/multipane_expand.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Expand/collapse</h4> +<p>When the device rotates, collapse the left pane view to only show the most important information. +Provide an <em>expand</em> control that allows the user to bring the left pane content back to its original +width and vice versa.</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/multipane_show.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Show/hide</h4> +<p>After rotating the device, show the right pane in fullscreen view. Use the Up icon in the action bar +to show the left panel and allow navigation to a different email. Hide the left panel by touching +the content in the detail panel.</p> + + </div> +</div> + +<h2 id="checklist">Checklist</h2> + +<ul> +<li> +<p>Plan in advance on how your app scales to different screen sizes and screen orientations.</p> +</li> +<li> +<p>Identify the most appropriate method for the panels in your compound views to reorganize + themselves when screen orientation changes.</p> +</li> +<li> +<p>Look for opportunities to consolidate your views into multi-panel compound views.</p> +</li> +<li> +<p>Make sure that your screens provide functional parity after the screen orientation + changes.</p> +</li> +</ul> diff --git a/docs/html/design/patterns/navigation.html b/docs/html/design/patterns/navigation.html deleted file mode 100644 index cad3682..0000000 --- a/docs/html/design/patterns/navigation.html +++ /dev/null @@ -1,268 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Navigation with Back and Up - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Navigation with Back and Up</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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 -guidelines for Back and Up will make your app's navigation predictable and reliable for your users.</p> -<p>Android 2.3 and earlier relied upon the system <em>Back</em> button for supporting navigation within an -app. With the introduction of action bars in Android 3.0, a second navigation mechanism appeared: -the <em>Up</em> button, consisting of the app icon and a left-point caret.</p> - -<img src="../static/content/navigation_with_back_and_up.png"> - -<h2>Up vs. Back</h2> -<p>The Up button is used to navigate within an application based on the hierarchical relationships -between screens. For instance, if screen A displays a list of items, and selecting an item leads to -screen B (which presents that item in more detail), then screen B should offer an Up button that -returns to screen A.</p> -<p>If a screen is the topmost one in an app (i.e. the home of the app), it should not present an Up -button.</p> -<p>The system Back key is used to navigate based on the history of screens the user has recently seen, -in reverse chronological order—in effect, the temporal relationships between screens.</p> -<p>When the previously viewed screen is also the hierarchical parent of the current screen, pressing -the Back key will have the same result as pressing an Up button -- this is a common occurrence. -However, unlike the Up button, which ensures the user remains within your app, the Back key can -return the user to the Home screen, or even to a different application.</p> - -<img src="../static/content/navigation_up_vs_back_gmail.png"> - -<p>The Back key also supports a few behaviors not directly tied to screen-to-screen navigation:</p> -<ul> -<li>Back dismisses floating windows (dialogs, popups)</li> -<li>Back dismisses contextual action bars, and removes the highlight from the selected items</li> -<li>Back hides the onscreen keyboard (IME)</li> -</ul> -<h2>Navigation Within Your App</h2> -<h4>Navigating to screens with multiple entry points</h4> -<p>Sometimes a screen doesn't have a strict position within the app's hierarchy, and can be reached -from multiple entry points—e.g., a settings screen which can be navigated to from any screen -in your app. In this case, the Up button should choose to return to the referring screen, behaving -identically to Back.</p> -<h4>Changing view within a screen</h4> -<p>Changing view options for a screen does not change the behavior of Up or Back: the screen is still -in the same place within the app's hierarchy, and no new navigation history is created.</p> -<p>Examples of such view changes are:</p> -<ul> -<li>Switching views using tabs and/or left-and-right swipes</li> -<li>Switching views using a dropdown (aka collapsed tabs)</li> -<li>Filtering a list</li> -<li>Sorting a list</li> -<li>Changing display characteristics (e.g. zooming)</li> -</ul> -<h4>Navigating between sibling screens</h4> -<p>When your app supports navigation from a list of items to a detail view of one of those items, it's -often desirable to support direction navigation from that item to another one which precedes or -follows it in the list. For example, in Gmail, it's easy to swipe left or right from a conversation -to view a newer or older one in the same Inbox. Just as when changing view within a screen, such -navigation does not change the behavior of Up or Back.</p> - -<img src="../static/content/navigation_between_siblings_gmail.png"> - -<p>However, a notable exception to this occurs when browsing between "related" detail views not tied -together by the referring list—for example, when browsing in the Market between apps from -the same developer, or albums by the same artist. In these cases, following each link does create -history, causing the Back button to step through each screen of related content which has been -viewed. Up should continue to bypass these related screens and navigate to the most recently viewed -container screen.</p> - -<img src="../static/content/navigation_between_siblings_market1.png"> - -<p>You have the ability to make the Up behavior even smarter based on your knowledge of detail -view. If we extend our Market sample from above, imagine the user has navigated from the last Book -viewed to the details for the Movie adaptation. In that case, Up can return to a container (Movies) -which the user had not previously navigated through.</p> - -<img src="../static/content/navigation_between_siblings_market2.png"> - -<h2>Navigation From Outside Your App</h2> -<p>There are two categories of navigation from outside your app to screens deep within the app's -hierarchy:</p> -<ul> -<li>App-to-app navigation, such as via intent completion.</li> -<li>System-to-app navigation, such as via notifications and home screen widgets.</li> -</ul> -<p>Gmail provides examples of each of these. For app-to-app navigation, a "Share" intent goes directly -to the compose screen. For system-to-app navigation, both a new message notification and a home -screen widget can bypass the Inbox screen, taking the user directly to a conversation view.</p> -<h4>App-to-app navigation</h4> -<p>When navigating deep into your app's hierarchy directly from another app via an intent, Back will -return to the referring app.</p> -<p>The Up button is handled as follows: -- If the destination screen is typically reached from one particular screen within your app, Up - should navigate to that screen. -- Otherwise, Up should navigate to the topmost ("Home") screen of your app.</p> -<p>For example, after choosing to share a book being viewed in Market, the user navigates directly to -Gmail's compose screen. From there, Up returns to the Inbox (which happens to be both the -typical referrer to compose, as well as the topmost screen of the app), while Back returns to -Market.</p> - -<img src="../static/content/navigation_from_outside_up.png"> - -<h4>System-to-app navigation</h4> -<p>If your app was reached via the system mechanisms of notifications or home screen widgets, Up -behaves as described for app-to-app navigation, above.</p> -<p>For the Back key, you should make navigation more predictably by inserting into the task's back -stack the complete upward navigation path to the app's topmost screen. This way, a user who has -forgotten how they entered your app can safely navigate to the app's topmost screen before exiting -it.</p> -<p>For example, Gmail's Home screen widget has a button for diving directly to its compose screen. -After following that path, the Back key first returns to the Inbox, and from there continues to -Home.</p> - -<img src="../static/content/navigation_from_outside_back.png"> - - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/navigation.jd b/docs/html/design/patterns/navigation.jd new file mode 100644 index 0000000..7e288ae --- /dev/null +++ b/docs/html/design/patterns/navigation.jd @@ -0,0 +1,204 @@ +page.title=Navigation with Back and Up +@jd:body + +<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 +guidelines for Back and Up will make your app's navigation predictable and reliable for your users.</p> +<p>Android 2.3 and earlier relied upon the system <em>Back</em> button for supporting navigation within an +app. With the introduction of action bars in Android 3.0, a second navigation mechanism appeared: +the <em>Up</em> button, consisting of the app icon and a left-point caret.</p> + +<img src="{@docRoot}design/media/navigation_with_back_and_up.png"> + +<h2 id="up-vs-back">Up vs. Back</h2> + +<p>The Up button is used to navigate within an app based on the hierarchical relationships +between screens. For instance, if screen A displays a list of items, and selecting an item leads to +screen B (which presents that item in more detail), then screen B should offer an Up button that +returns to screen A.</p> +<p>If a screen is the topmost one in an app (that is, the app's home), it should not present an Up +button.</p> + +<p>The system Back button is used to navigate, in reverse chronological order, through the history +of screens the user has recently worked with. It is generally based on the temporal relationships +between screens, rather than the app's hierarchy.</p> + +<p>When the previously viewed screen is also the hierarchical parent of the current screen, pressing +the Back button has the same result as pressing an Up button—this is a common +occurrence. However, unlike the Up button, which ensures the user remains within your app, the Back +button can return the user to the Home screen, or even to a different app.</p> + +<img src="{@docRoot}design/media/navigation_up_vs_back_gmail.png"> + +<p>The Back button also supports a few behaviors not directly tied to screen-to-screen navigation: +</p> +<ul> +<li>Dismisses floating windows (dialogs, popups)</li> +<li>Dismisses contextual action bars, and removes the highlight from the selected items</li> +<li>Hides the onscreen keyboard (IME)</li> +</ul> +<h2 id="within-app">Navigation Within Your App</h2> + +<h4>Navigating to screens with multiple entry points</h4> +<p>Sometimes a screen doesn't have a strict position within the app's hierarchy, and can be reached +from multiple entry points—such as a settings screen that can be reached from any other screen +in your app. In this case, the Up button should choose to return to the referring screen, behaving +identically to Back.</p> +<h4>Changing view within a screen</h4> +<p>Changing view options for a screen does not change the behavior of Up or Back: the screen is still +in the same place within the app's hierarchy, and no new navigation history is created.</p> +<p>Examples of such view changes are:</p> +<ul> +<li>Switching views using tabs and/or left-and-right swipes</li> +<li>Switching views using a dropdown (aka collapsed tabs)</li> +<li>Filtering a list</li> +<li>Sorting a list</li> +<li>Changing display characteristics (such as zooming)</li> +</ul> +<h4>Navigating between sibling screens</h4> +<p>When your app supports navigation from a list of items to a detail view of one of those items, it's +often desirable to support direction navigation from that item to another one which precedes or +follows it in the list. For example, in Gmail, it's easy to swipe left or right from a conversation +to view a newer or older one in the same Inbox. Just as when changing view within a screen, such +navigation does not change the behavior of Up or Back.</p> + +<img src="{@docRoot}design/media/navigation_between_siblings_gmail.png"> + +<p>However, a notable exception to this occurs when browsing between related detail views not tied +together by the referring list—for example, when browsing in the Play Store between apps from +the same developer, or albums by the same artist. In these cases, following each link does create +history, causing the Back button to step through each previously viewed screen. Up should continue +to bypass these related screens and navigate to the most recently viewed container screen.</p> + +<img src="{@docRoot}design/media/navigation_between_siblings_market1.png"> + +<p>You have the ability to make the Up behavior even smarter based on your knowledge of detail +view. Extending the Play Store example from above, imagine the user has navigated from the last +Book viewed to the details for the Movie adaptation. In that case, Up can return to a container +(Movies) which the user hasn't previously navigated through.</p> + +<img src="{@docRoot}design/media/navigation_between_siblings_market2.png"> + +<h2 id="into-your-app">Navigation into Your App via Home Screen Widgets and Notifications</h2> + +<p>You can use Home screen widgets or notifications to help your users navigate directly to screens +deep within your app's hierarchy. For example, Gmail's Inbox widget and new message notification can +both bypass the Inbox screen, taking the user directly to a conversation view.</p> + +<p>For both of these cases, handle the Up button as follows:</p> + +<ul> +<li><em>If the destination screen is typically reached from one particular screen within your +app</em>, Up should navigate to that screen.</li> +<li><em>Otherwise</em>, Up should navigate to the topmost ("Home") screen of your app.</li> +</ul> + +<p>In the case of the Back button, you should make navigation more predictable by inserting into the +task's back stack the complete upward navigation path to the app's topmost screen. This allows users +who've forgotten how they entered your app to navigate to the app's topmost screen before +exiting.</p> + +<p>As an example, Gmail's Home screen widget has a button for diving directly to its compose +screen. Up or Back from the compose screen would take the user to the Inbox, and from there the +Back button continues to Home.</p> + +<img src="{@docRoot}design/media/navigation_from_outside_back.png"> + +<h4>Indirect notifications</h4> + +<p>When your app needs to present information about multiple events simultaneously, it can use a +single notification that directs the user to an interstitial screen. This screen summarizes these +events, and provides paths for the user to dive deeply into the app. Notifications of this style are +called <em>indirect notifications</em>.</p> + +<p>Unlike standard (direct) notifications, pressing Back from an indirect notification's +interstitial screen returns the user to the point the notification was triggered from—no +additional screens are inserted into the back stack. Once the user proceeds into the app from its +interstitial screen, Up and Back behave as for standard notifications, as described above: +navigating within the app rather than returning to the interstitial.</p> + +<p>For example, suppose a user in Gmail receives an indirect notification from Calendar. Touching +this notification opens the interstitial screen, which displays reminders for several different +events. Touching Back from the interstitial returns the user to Gmail. Touching on a particular +event takes the user away from the interstitial and into the full Calendar app to display details of +the event. From the event details, Up and Back navigate to the top-level view of Calendar.</p> + +<img src="{@docRoot}design/media/navigation_indirect_notification.png"> + +<h4>Pop-up notifications</h4> + +<p><em>Pop-up notifications</em> bypass the notification drawer, instead appearing directly in +front of the user. They are rarely used, and <strong>should be reserved for occasions where a timely +response is required and the interruption of the user's context is necessary</strong>. For example, +Talk uses this style to alert the user of an invitation from a friend to join a video chat, as this +invitation will automatically expire after a few seconds.</p> + +<p>In terms of navigation behavior, pop-up notifications closely follow the behavior of an indirect +notification's interstitial screen. Back dismisses the pop-up notification. If the user navigates +from the pop-up into the notifying app, Up and Back follow the rules for standard notifications, +navigating within the app.</p> + +<img src="{@docRoot}design/media/navigation_popup_notification.png"> + +<h2 id="between-apps">Navigation Between Apps</h2> + +<p>One of the fundamental strengths of the Android system is the ability for apps to activate each +other, giving the user the ability to navigate directly from one app into another. For example, an +app that needs to capture a photo can activate the Camera app, which will return the photo +to the referring app. This is a tremendous benefit to both the developer, who can easily leverage +code from other apps, and the user, who enjoys a consistent experience for commonly performed +actions.</p> + +<p>To understand app-to-app navigation, it's important to understand the Android framework behavior +discussed below.</p> + +<h4>Activities, tasks, and intents</h4> + +<p>In Android, an <strong>activity</strong> is an application component that defines a screen of +information and all of the associated actions the user can perform. Your app is a collection of +activities, consisting of both the activities you create and those you re-use from other apps.</p> + +<p>A <strong>task</strong> is the sequence of activities a user follows to accomplish a goal. A +single task can make use of activities from just one app, or may draw on activities from a number +of different apps.</p> + +<p>An <strong>intent</strong> is a mechanism for one app to signal it would like another +app's assistance in performing an action. An app's activities can indicate which intents +they can respond to. For common intents such as "Share", the user may have many apps installed +that can fulfill that request.</p> + +<h4>Example: navigating between apps to support sharing</h4> + +<p>To understand how activities, tasks, and intents work together, consider how one app allows users +to share content by using another app. For example, launching the Play Store app from Home begins +new Task A (see figure below). After navigating through the Play Store and touching a promoted book +to see its details, the user remains in the same task, extending it by adding activities. Triggering +the Share action prompts the user with a dialog listing each of the activities (from different apps) +which have registered to handle the Share intent.</p> + +<img src="{@docRoot}design/media/navigation_between_apps_inward.png"> + +<p>When the user elects to share via Gmail, Gmail's compose activity is added as a continuation of +Task A—no new task is created. If Gmail had its own task running in the background, it would +be unaffected.</p> + +<p>From the compose activity, sending the message or touching the Back button returns the user to +the book details activity. Subsequent touches of Back continue to navigate back through the Play +Store, ultimately arriving at Home.</p> + +<img src="{@docRoot}design/media/navigation_between_apps_back.png"> + +<p>However, by touching Up from the compose activity, the user indicates a desire to remain within +Gmail. Gmail's conversation list activity appears, and a new Task B is created for it. New tasks are +always rooted to Home, so touching Back from the conversation list returns there.</p> + +<img src="{@docRoot}design/media/navigation_between_apps_up.png"> + +<p>Task A persists in the background, and the user may return to it later (for example, via the +Recents screen). If Gmail already had its own task running in the background, it would be replaced +with Task B—the prior context is abandoned in favor of the user's new goal.</p> + +<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> diff --git a/docs/html/design/patterns/new-4-0.html b/docs/html/design/patterns/new-4-0.html deleted file mode 100644 index 272b079..0000000 --- a/docs/html/design/patterns/new-4-0.html +++ /dev/null @@ -1,224 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - New in Android 4.0 - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>New in Android 4.0</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Navigation bar</h4> -<p>Android 4.0 removes the need for traditional hardware keys on phones by replacing them with a -virtual navigation bar that houses the Back, Home and Recents buttons. Read the -<a href="../patterns/compatibility.html">Compatibility</a> pattern to learn how the OS adapts to -phones with hardware buttons and how pre-Android 3.0 apps that rely on menu keys are supported.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/whats_new_nav_bar.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Action bar</h4> -<p>The action bar is the most important structural element of an Android app. It provides consistent -navigation across the platform and allows your app to surface actions.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/whats_new_action_bar.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Multi-pane layouts</h4> -<p>Creating apps that scale well across different form factors and screen sizes is important in the -Android world. Multi-pane layouts allow you to combine different activities that show separately on -smaller devices into richer compound views for tablets.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/whats_new_multipanel.png"> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-7"> - -<h4>Selection</h4> -<p>The long press gesture which was traditionally used to show contextual actions for objects is now -used for data selection. When selecting data, contextual action bars allow you to surface actions.</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/whats_new_multiselect.png"> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/new-4-0.jd b/docs/html/design/patterns/new-4-0.jd new file mode 100644 index 0000000..91ebba7 --- /dev/null +++ b/docs/html/design/patterns/new-4-0.jd @@ -0,0 +1,71 @@ +page.title=New in Android 4.0 +@jd:body + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4>Navigation bar</h4> +<p>Android 4.0 removes the need for traditional hardware keys on phones by replacing them with a +virtual navigation bar that houses the Back, Home and Recents buttons. Read the +<a href="{@docRoot}design/patterns/compatibility.html">Compatibility</a> pattern to learn how the OS adapts to +phones with hardware buttons and how pre-Android 3.0 apps that rely on menu keys are supported.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/whats_new_nav_bar.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4>Action bar</h4> +<p>The action bar is the most important structural element of an Android app. It provides consistent +navigation across the platform and allows your app to surface actions.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/whats_new_action_bar.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4>Multi-pane layouts</h4> +<p>Creating apps that scale well across different form factors and screen sizes is important in the +Android world. Multi-pane layouts allow you to combine different activities that show separately on +smaller devices into richer compound views for tablets.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/whats_new_multipanel.png"> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-7"> + +<h4>Selection</h4> +<p>The long press gesture which was traditionally used to show contextual actions for objects is now +used for data selection. When selecting data, contextual action bars allow you to surface actions.</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/whats_new_multiselect.png"> + + </div> +</div> diff --git a/docs/html/design/patterns/notifications.html b/docs/html/design/patterns/notifications.jd index c5045ae..ad88a01 100644 --- a/docs/html/design/patterns/notifications.html +++ b/docs/html/design/patterns/notifications.jd @@ -1,106 +1,5 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Notifications - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Notifications</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - +page.title=Notifications +@jd:body <p>The notification system allows your app to keep the user informed about important events, such as new messages in a chat app or a calendar event.</p> @@ -124,7 +23,7 @@ synchronous form of communication: there is another user actively waiting on you Calendar events are another good example of when to use a notification and grab the user's attention, because the event is imminent, and calendar events often involve other people.</p> -<img src="../static/content/notifications_pattern_real_time_people.png"> +<img src="{@docRoot}design/media/notifications_pattern_real_time_people.png"> <div class="vspace size-2"> </div> @@ -168,17 +67,17 @@ develop a widget that they can choose to place on their home screen.</p> </div> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_social_fail.png"> + <img src="{@docRoot}design/media/notifications_pattern_social_fail.png"> </div> </div> -<h2>Design Guidelines</h2> +<h2 id="design-guidelines">Design Guidelines</h2> <div class="layout-content-row"> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_anatomy.png"> + <img src="{@docRoot}design/media/notifications_pattern_anatomy.png"> </div> <div class="layout-content-col span-6"> @@ -200,7 +99,7 @@ stacked (see <em>Stacked notifications</em> below) and references multiple items the user is taken to a hierarchy level below your app's top-level, insert navigation into your app's back stack to allow them to navigate to your app's top level using the system back key. For more information, see the chapter on <em>System-to-app navigation</em> in the -<a href="../patterns/navigation.html">Navigation</a> design pattern.</p> +<a href="{@docRoot}design/patterns/navigation.html">Navigation</a> design pattern.</p> <h4>Timestamps for time sensitive events</h4> <p>By default, standard Android notifications include a timestamp in the upper right corner. Consider whether the timestamp is valuable in the context of your notification. If the timestamp is not @@ -218,11 +117,11 @@ an altogether new notification object. Instead, stack the notification.</p> notifications of a particular kind are pending.</p> <p><strong>Don't</strong>:</p> -<img src="../static/content/notifications_pattern_additional_fail.png"> +<img src="{@docRoot}design/media/notifications_pattern_additional_fail.png"> <p><strong>Do</strong>:</p> -<img src="../static/content/notifications_pattern_additional_win.png"> +<img src="{@docRoot}design/media/notifications_pattern_additional_win.png"> <p>If you keep the summary and detail information on different screens, a stacked notification may need to open to a different place in the app than a single notification.</p> @@ -248,7 +147,7 @@ hides automatically.</p> </div> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_phone_ticker.png"> + <img src="{@docRoot}design/media/notifications_pattern_phone_ticker.png"> </div> </div> @@ -269,12 +168,12 @@ currently pending.</p> <li>Use color to distinguish your app from others. Notification icons should generally be monochrome.</li> </ul> -<h2>Interacting With Notifications</h2> +<h2 id="interacting-with-notifications">Interacting With Notifications</h2> <div class="layout-content-row"> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_phone_icons.png"> + <img src="{@docRoot}design/media/notifications_pattern_phone_icons.png"> </div> <div class="layout-content-col span-6"> @@ -297,7 +196,7 @@ notification drawer is opened by touching anywhere inside the notification area. </div> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_tablet.png"> + <img src="{@docRoot}design/media/notifications_pattern_tablet.png"> </div> </div> @@ -305,7 +204,7 @@ notification drawer is opened by touching anywhere inside the notification area. <div class="layout-content-row"> <div class="layout-content-col span-6"> - <img src="../static/content/notifications_pattern_ongoing_music.png"> + <img src="{@docRoot}design/media/notifications_pattern_ongoing_music.png"> </div> <div class="layout-content-col span-6"> @@ -334,57 +233,4 @@ and toasts can echo back that an action has been successfully taken.</p> <div class="vspace size-1"> </div> -<img src="../static/content/notifications_pattern_dialog_toast.png"> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> +<img src="{@docRoot}design/media/notifications_pattern_dialog_toast.png"> diff --git a/docs/html/design/patterns/pure-android.html b/docs/html/design/patterns/pure-android.html deleted file mode 100644 index 507558a..0000000 --- a/docs/html/design/patterns/pure-android.html +++ /dev/null @@ -1,288 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Pure Android - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Pure Android</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Most developers want to distribute their apps on multiple platforms. As you plan your app for -Android, keep in mind that different platforms play by different rules and conventions. Design -decisions that make perfect sense on one platform will look and feel misplaced in the context of a -different platform. While a "design once, ship anywhere" approach might save you time up-front, you -run the very real risk of creating inconsistent apps that alienate users. Consider the following -guidelines to avoid the most common traps and pitfalls.</p> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - -<h4>Don't mimic UI elements from other platforms</h4> -<p>Platforms typically provide a carefully designed set of UI elements that are themed in a very -distinctive fashion. For example, some platforms advocate rounded corners for their buttons, others -use gradients in their title bars. In some cases, elements may have the same purpose, but are -designed to work a bit differently.</p> -<p>As you build your app for Android, don't carry over themed UI elements from other platforms and -don't mimic their specific behaviors. Review the <a href="../building- -blocks/index.html">Building Blocks</a> section in this styleguide to learn about Android's most important UI elements -and the way they look in the system default themes. Also examine Android's platform apps to get a -sense of how elements are applied in the context of an app. If you want to customize the theme of UI -elements, customize carefully according to your specific branding - and not according to the -conventions of a different platform.</p> - - </div> - <div class="layout-content-col span-8"> - - <img src="../static/content/migrating_ui_elements.png"> - <div class="figure-caption"> - Sampling of UI elements from Android, iOS and Windows Phone 7. - </div> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - -<h4>Don't carry over platform-specific icons</h4> -<p>Platforms typically provide sets of icons for common functionality, such as sharing, creating a new -document or deleting.</p> -<p>As you are migrating your app to Android, please swap out platform-specific icons with their Android -counterparts.</p> -<p>You can find a wide variety of icons for use in your app in the Android SDK.</p> - - </div> - <div class="layout-content-col span-8"> - - <img src="../static/content/migrating_icons.png"> - <div class="figure-caption"> - Sampling of icons from Android, iOS and Windows Phone 7. - </div> - - </div> -</div> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - -<h4>Don't use bottom tab bars</h4> -<p>Other platforms use the bottom tab bar to switch between the app's views. Per platform convention, -Android's tabs for view control are shown in action bars at the top of the screen instead. In -addition, Android apps may use a bottom bar to display actions on a split action bar.</p> -<p>You should follow this guideline to create a consistent experience with other apps on the Android -platform and to avoid confusion between actions and view switching on Android.</p> -<p>For more information on how to properly use action bars for view control, see -<a href="../patterns/actionbar.html">Action Bars</a>.</p> - - </div> - <div class="layout-content-col span-8"> - - <img src="../static/content/migrating_ios_dialers.png"> - <div class="figure-caption"> - Android dialer with tabs in an action bar vs. bottom tabs in iOS. - </div> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - -<h4>Don't use labeled back buttons on action bars</h4> -<p>Other platforms use an explicit back button with label to allow the user to navigate up the -application's hierarchy. Instead, Android uses the main action bar's app icon for hierarchical -navigation and the navigation bar's back button for temporal navigation. For more information, -please review the <a href="../patterns/navigation.html">Navigation</a> pattern.</p> -<p>Follow this guideline to provide a consistent navigation experience across the platform.</p> - - </div> - <div class="layout-content-col span-8"> - - <img src="../static/content/migrating_ios_galleries.png"> - <div class="figure-caption"> - Android action bar with up caret vs. iOS labeled "Back" button. - </div> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - -<h4>Don't use right-pointing carets on line items</h4> -<p>A common pattern on other platforms is the display of right-pointing carets on line items that allow -the user to drill deeper into additional content.</p> -<p>Android does not use such indicators on drill-down line items. Avoid them to stay consistent with -the platform and in order to not have the user guess as to what the meaning of those carets may be.</p> - - </div> - <div class="layout-content-col span-8"> - - <img src="../static/content/migrating_ios_settings.png"> - <div class="figure-caption"> - Android settings without right-pointing carets in line items vs. iOS settings. - </div> - - </div> -</div> - -<h2>Device Independence</h2> - -<p>Remember that your app will run on a wide variety of different screen sizes. Create visual assets -for different screen sizes and densities and make use of concepts such as multi-pane layouts to -appropriately scale your UI on different device form factors.</p> -<p>For more information, read <a href="../style/devices-displays.html">Devices and Displays</a> as -well as <a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a> in this design guide.</p> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/pure-android.jd b/docs/html/design/patterns/pure-android.jd new file mode 100644 index 0000000..77813c0 --- /dev/null +++ b/docs/html/design/patterns/pure-android.jd @@ -0,0 +1,164 @@ +page.title=Pure Android +@jd:body + +<p>Most developers want to distribute their apps on multiple platforms. As you plan your app for +Android, keep in mind that different platforms play by different rules and conventions. Design +decisions that make perfect sense on one platform will look and feel misplaced in the context of a +different platform. While a "design once, ship anywhere" approach might save you time up-front, you +run the very real risk of creating inconsistent apps that alienate users. Consider the following +guidelines to avoid the most common traps and pitfalls.</p> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't mimic UI elements from other platforms</h4> +<p>Platforms typically provide a carefully designed set of UI elements that are themed in a very +distinctive fashion. For example, some platforms advocate rounded corners for their buttons, others +use gradients in their title bars. In some cases, elements may have the same purpose, but are +designed to work a bit differently.</p> +<p>As you build your app for Android, don't carry over themed UI elements from other platforms and +don't mimic their specific behaviors. Review the +<a href="{@docRoot}design/building-blocks/index.html">Building Blocks</a> +section in this styleguide to learn about Android's most important UI elements +and the way they look in the system default themes. Also examine Android's platform apps to get a +sense of how elements are applied in the context of an app. If you want to customize the theme of UI +elements, customize carefully according to your specific branding - and not according to the +conventions of a different platform.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_ui_elements.png"> + <div class="figure-caption"> + Sampling of UI elements from Android, iOS and Windows Phone 7. + </div> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't carry over platform-specific icons</h4> +<p>Platforms typically provide sets of icons for common functionality, such as sharing, creating a new +document or deleting.</p> +<p>As you are migrating your app to Android, please swap out platform-specific icons with their Android +counterparts.</p> +<p>You can find a wide variety of icons for use in your app on the +<a href="{@docRoot}design/downloads/index.html">Downloads</a> page.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_icons.png"> + <div class="figure-caption"> + Sampling of icons from Android, iOS and Windows Phone 7. + </div> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't use bottom tab bars</h4> +<p>Other platforms use the bottom tab bar to switch between the app's views. Per platform convention, +Android's tabs for view control are shown in action bars at the top of the screen instead. In +addition, Android apps may use a bottom bar to display actions on a split action bar.</p> +<p>You should follow this guideline to create a consistent experience with other apps on the Android +platform and to avoid confusion between actions and view switching on Android.</p> +<p>For more information on how to properly use action bars for view control, see +<a href="{@docRoot}design/patterns/actionbar.html">Action Bars</a>.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_ios_dialers.png"> + <div class="figure-caption"> + Android dialer with tabs in an action bar vs. bottom tabs in iOS. + </div> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't hardcode links to other apps</h4> +<p>In some cases you might want your app to take advantage of another app's feature set. For +example, you may want to share the content that your app created via a social network or messaging +app, or view the content of a weblink in a browser. Don't use hard-coded, explicit links to +particular apps to achieve this. Instead, use Android's intent API to launch an activity chooser +which lists all applications that are set up to handle the particular request. This lets the user +complete the task with their preferred app. For sharing in particular, consider using the <em>Share +Action Provider</em> in your action bar to provide faster access to the user's most recently used +sharing target.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_intents.png"> + <div class="figure-caption"> + Link to other apps with the activity chooser or use the <em>Share Action Provider</em> in the + action bar. + </div> + + </div> +</div> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't use labeled back buttons on action bars</h4> +<p>Other platforms use an explicit back button with label to allow the user to navigate up the +application's hierarchy. Instead, Android uses the main action bar's app icon for hierarchical +navigation and the navigation bar's back button for temporal navigation. For more information, +please review the <a href="{@docRoot}design/patterns/navigation.html">Navigation</a> pattern.</p> +<p>Follow this guideline to provide a consistent navigation experience across the platform.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_ios_galleries.png"> + <div class="figure-caption"> + Android action bar with up caret vs. iOS labeled "Back" button. + </div> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + +<h4>Don't use right-pointing carets on line items</h4> +<p>A common pattern on other platforms is the display of right-pointing carets on line items that allow +the user to drill deeper into additional content.</p> +<p>Android does not use such indicators on drill-down line items. Avoid them to stay consistent with +the platform and in order to not have the user guess as to what the meaning of those carets may be.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/migrating_ios_settings.png"> + <div class="figure-caption"> + Android settings without right-pointing carets in line items vs. iOS settings. + </div> + + </div> +</div> + +<h2 id="device-independence">Device Independence</h2> + +<p>Remember that your app will run on a wide variety of different screen sizes. Create visual assets +for different screen sizes and densities and make use of concepts such as multi-pane layouts to +appropriately scale your UI on different device form factors.</p> +<p>For more information, read <a href="{@docRoot}design/style/devices-displays.html">Devices and Displays</a> as +well as <a href="{@docRoot}design/patterns/multi-pane-layouts.html">Multi-pane Layouts</a> in this design guide.</p> diff --git a/docs/html/design/patterns/selection.html b/docs/html/design/patterns/selection.html deleted file mode 100644 index 37dcab5..0000000 --- a/docs/html/design/patterns/selection.html +++ /dev/null @@ -1,252 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Selection - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Selection</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Android 3.0 introduced the <em>long press</em> gesture—that is, a touch that's held in the same -position for a moment—as the global gesture to select data. This affects the way you should -handle multi-select and contextual actions in your apps.</p> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>What has changed?</h4> -<p>In previous versions of Android, the long press gesture was universally used to display contextual -actions for a given data item in a contextual menu.</p> -<p>This pattern changed with Android 3.0. The long press gesture is now used to select data, combining -contextual actions and selection management functions for selected data into a new element called -the contextual action bar (CAB).</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/selection_context_menu.png"> - <div class="figure-caption"> - Traditional use of the long press gesture to show contextual menus. - </div> - - </div> -</div> - -<h4>Using the contextual action bar (CAB)</h4> -<p>The selection CAB is a temporary action bar that overlays your app's current action bar while data -is selected. It appears after the user long presses on a selectable data item.</p> - -<img src="../static/content/selection_cab_big.png"> - -<div class="vspace size-1"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<p>From here the user can:</p> -<ul> -<li>Select additional data items by touching them.</li> -<li>Trigger an action from the CAB that applies to all highlighted 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> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/selection_cab_example.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Selecting CAB actions</h4> -<p>You can decide which actions and elements appear in the CAB. Use the guidelines in the <a href="actionbar.html">Action Bar -pattern</a> to decide which items to surface at the top level and which to move to the -action overflow.</p> -<h4>Dynamically adjust CAB actions</h4> -<p>In most cases you need to adjust the actions in the CAB dynamically as the user adds more items to -the selection. Actions that apply to a single selected data item don't necessarily apply to multiple -selected data items of the same kind.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/selection_adjusting_actions.png"> - <div class="figure-caption"> - Adjusting actions in the CAB as additional items are selected. - </div> - - </div> -</div> - -<h2>Checklist</h2> -<ul> -<li> -<p>Whenever your app supports the selection of multiple data items, make use of the contextual action - bar (CAB).</p> -</li> -<li> -<p>Reserve the long press gesture for selection exclusively. Don't use it to display traditional - contextual menus.</p> -</li> -<li> -<p>If you don't support multi-selection within a list, long press should do nothing.</p> -</li> -<li> -<p>Plan the actions you want to display inside of a CAB in the same way you would plan the actions - inside your app's action bar.</p> -</li> -</ul> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/selection.jd b/docs/html/design/patterns/selection.jd new file mode 100644 index 0000000..e3ee90e --- /dev/null +++ b/docs/html/design/patterns/selection.jd @@ -0,0 +1,100 @@ +page.title=Selection +@jd:body + +<p>Android 3.0 introduced the <em>long press</em> gesture—that is, a touch that's held in the same +position for a moment—as the global gesture to select data. This affects the way you should +handle multi-select and contextual actions in your apps.</p> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>What has changed?</h4> +<p>In previous versions of Android, the long press gesture was universally used to display contextual +actions for a given data item in a contextual menu.</p> +<p>This pattern changed with Android 3.0. The long press gesture is now used to select data, combining +contextual actions and selection management functions for selected data into a new element called +the contextual action bar (CAB).</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/selection_context_menu.png"> + <div class="figure-caption"> + Traditional use of the long press gesture to show contextual menus. + </div> + + </div> +</div> + +<h4>Using the contextual action bar (CAB)</h4> +<p>The selection CAB is a temporary action bar that overlays your app's current action bar while data +is selected. It appears after the user long presses on a selectable data item.</p> + +<img src="{@docRoot}design/media/selection_cab_big.png"> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<p>From here the user can:</p> +<ul> +<li>Select additional data items by touching them.</li> +<li>Trigger an action from the CAB that applies to all highlighted 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> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/selection_cab_example.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Selecting CAB actions</h4> +<p>You can decide which actions and elements appear in the CAB. Use the guidelines in the <a href="actionbar.html">Action Bar +pattern</a> to decide which items to surface at the top level and which to move to the +action overflow.</p> +<h4>Dynamically adjust CAB actions</h4> +<p>In most cases you need to adjust the actions in the CAB dynamically as the user adds more items to +the selection. Actions that apply to a single selected data item don't necessarily apply to multiple +selected data items of the same kind.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/selection_adjusting_actions.png"> + <div class="figure-caption"> + Adjusting actions in the CAB as additional items are selected. + </div> + + </div> +</div> + +<h2 id="checklist">Checklist</h2> + +<ul> +<li> +<p>Whenever your app supports the selection of multiple data items, make use of the contextual action + bar (CAB).</p> +</li> +<li> +<p>Reserve the long press gesture for selection exclusively. Don't use it to display traditional + contextual menus.</p> +</li> +<li> +<p>If you don't support multi-selection within a list, long press should do nothing.</p> +</li> +<li> +<p>Plan the actions you want to display inside of a CAB in the same way you would plan the actions + inside your app's action bar.</p> +</li> +</ul> diff --git a/docs/html/design/patterns/settings.jd b/docs/html/design/patterns/settings.jd new file mode 100644 index 0000000..3b28b84 --- /dev/null +++ b/docs/html/design/patterns/settings.jd @@ -0,0 +1,689 @@ +page.title=Settings +@jd:body + +<p>Settings is a place in your app where users indicate their preferences for how your app should +behave. This benefits users because:</p> + +<ul> +<li>You don't need to interrupt them with the same questions over and over when certain situations +arise. The settings predetermine what will always happen in those situations (see design +principle: <a href="{@docRoot}design/get-started/principles.html#decide-for-me">Decide for me but +let me have the final say</a>).</li> +<li>You help them feel at home and in control (see design principle: +<a href="{@docRoot}design/get-started/principles.html#make-it-mine">Let me make it mine</a>).</li> +</ul> + +<h2 id="flow-structure">Flow and Structure</h2> + +<h4 id="settings-access">Provide access to Settings in the action overflow</h4> + +<p>Settings is given low prominence in the UI because it's not frequently needed. Even if there's +room in the <a href="{@docRoot}design/patterns/actionbar.html">action bar</a>, never make Settings +an action button. Always keep it in the action overflow and label it "Settings". Place it below +all other items except "Help".</p> + +<img src="{@docRoot}design/media/settings_overflow.png"> + +<div class="vspace size-2"> </div> + +<h4 id="what-to-make-a-setting">Avoid the temptation to make everything a setting</h4> + +<p>Because Settings is a few navigational steps away, no matter how many items you have, they'll +never clutter up the core part of your UI. This may seem like good news, but it also poses a +challenge.</p> + +<p>Settings can be a tempting place to keep a lot of stuff—like a hall closet where things +get stashed when you tidy up before company comes over. It's not a place where you spend lots of +time, so it's easy to rationalize and ignore its cluttered condition. But when users visit +Settings—however infrequently—they'll have the same expectations for the experience as +they do everywhere else in your app. More settings means more choices to make, and too many are +overwhelming.</p> + +<p>So don't punt on the difficult product decisions and debates that can bring on the urge to +"just make it a setting". For each control you're considering adding to Settings, make sure it +meets the bar:</p> + +<img src="{@docRoot}design/media/settings_flowchart.png"> + +<div class="vspace size-3"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-5 with-callouts"> + +<h4 id="group-settings">If you still have lots of settings, group related settings together</h4> + +<p>The number of items an average human can hold in short-term memory is 7±2. If you +present a list of 10 or more settings (even after applying the criteria above), users will have +more difficulty scanning, comprehending, and processing them.</p> + +<p>You can remedy this by dividing some or all of the settings into groups, effectively turning +one long list into multiple shorter lists. A group of related settings can be presented in one of +two ways:</p> + +<ol> +<li><h4>Under a section divider</h4></li> +<li><h4>In a separate subscreen</h4></li> +</ol> + +<p>You can use one or both these grouping techniques to organize your app's settings.</p> + +<p>For example, in the main screen of the Android Settings app, each item in the list navigates +to a subscreen of related settings. In addition, the items themselves are grouped under section +dividers.</p> + + </div> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/settings_grouping.png"> + + </div> +</div> + +<p>Grouping settings is not an exact science, but here's some advice for how to approach it, based +on the total number of settings in your app.</p> + +<div class="vspace size-1"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-2"> + +<h4>7 or fewer</h4> + + </div> + <div class="layout-content-col span-11"> + +<p>Don't group them at all. It won't benefit users and will seem like overkill.</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-2"> + +<h4>8 to 10</h4> + + </div> + <div class="layout-content-col span-11"> + +<p>Try grouping related settings under 1 or 2 section dividers. If you have any "singletons" +(settings that don't relate to any other settings and can't be grouped under your section +dividers), treat them as follows:</p> + +<ul> +<li>If they include some of your most important settings, list them at the top without a section +divider.</li> +<li>Otherwise, list them at the bottom with a section divider called "OTHER", in order of +importance.</li> +</ul> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-2"> + +<h4>11 to 15</h4> + + </div> + <div class="layout-content-col span-11"> + +<p>Same advice as above, but try 2 to 4 section dividers.</p> + +<p>Also, try the following to reduce the list:</p> + +<ul> +<li>If 2 or more of the settings are mainly for power users, move them out of your main Settings +screen and into an "Advanced" subscreen. Place an item in the action overflow called "Advanced" to +navigate to it.</li> +<li>Look for "doubles": two settings that relate to one another, but not to any other settings. +Try to combine them into one setting, using the design patterns described later in this section. +For example, you might be able to redesign two related checkbox settings into one multiple choice +setting.</li> +</ul> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-2"> + +<h4>16 or more</h4> + + </div> + <div class="layout-content-col span-11"> + +<p>If you have any instances of 4 or more related settings, group them under a subscreen. Then use +the advice suggested above for the reduced list size.</p> + + </div> +</div> + + +<h2 id="patterns">Design Patterns</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Checkbox</h4> +<p>Use this pattern for a setting that is either selected or not selected.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_checkbox.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Multiple choice</h4> +<p>Use this pattern for a setting that needs to present a discrete set of options, from which the +user can choose only one.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_multiple_choice.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Slider</h4> +<p>Use this pattern for a setting where the range of values are not discrete and fall along a +continuum.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_slider.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Date/time</h4> +<p>Use this pattern for a setting that needs to collect a date and/or time from the user.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_date_time.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Subscreen navigation</h4> +<p>Use this pattern for navigating to a subscreen or sequence of subscreens that guide the user +through a more complex setup process.</p> +<ul> +<li>If navigating to a single subscreen, use the same title in both the subscreen and the label +navigating to it.</li> +<li>If navigating to a sequence of subscreens (as in this example), use a title that describes the +first step in the sequence.</li> +</ul> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_subscreen_navigation.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>List subscreen</h4> +<p>Use this pattern for a setting or category of settings that contains a list of equivalent items. +</p> +<p>The label provides the name of the item, and secondary text may be used for status. (In this +example, status is reinforced with an icon to the right of the label.) Any actions associated with +the list appear in the action bar rather than the list itself.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_list_subscreen.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Master on/off switch</h4> +<p>Use this pattern for a category of settings that need a mechanism for turning on or off as a +whole.</p> +<p>An on/off switch is placed as the first item in the action bar of a subscreen. When the switch +is turned off, the items in the list disappear, replaced by text that describes why the list is +empty. If any actions require the switch to be on, they become disabled.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_master_on_off.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<div class="vspace size-2"> </div> + +<p>You can also echo the master on/off switch in the menu item that leads to the subscreen. +However, you should only do this in cases where users rarely need to access the subscreen once +it's initially set up and more often just want to toggle the switch.</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_master_on_off_2.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Individual on/off switch</h4> +<p>Use this pattern for an individual setting that requires a more elaborate description than can +be provided in checkbox form.</p> +<p>The on/off switch only appears in the subscreen so that users aren't able to toggle it without +also being exposed to the descriptive text. Secondary text appears below the setting label to +reflect the current selection.</p> +<p>In this example, Android Beam is on by default. Since users might not know what this setting +does, we made the status more descriptive than just "On".</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_individual_on_off.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Dependency</h4> +<p>Use this pattern for a setting that changes availability based on the value of another setting. +</p> +<p>The disabled setting appears below its dependency, without any indentation. If the setting +includes a status line, it says "Unavailable", and if the reason isn't obvious, a brief +explanation is included in the status.</p> +<p>If a given setting is a dependency to 3 or more settings, consider using a subscreen with a +master on/off switch so that your main settings screen isn't cluttered by lots of disabled items. +</p> + + </div> + <div class="layout-content-col span-10"> + +<img src="{@docRoot}design/media/settings_dependency.png"> + + </div> +</div> + +<h2 id="defaults">Defaults</h2> + +<p>Take great care in choosing default values for each of your settings. Because settings +determine app behavior, your choices will contribute to users' first impressions of your app. Even +though users can change settings, they'll expect the initial states to be sensible. The following +questions (when applicable) may help inform your decisions:</p> + +<ul> +<li>Which choice would most users be likely to choose on their own if there were no default?</li> +<li>Which choice is the most neutral or middle-of-the-road?</li> +<li>Which choice is the least risky, controversial, or over-the-top?</li> +<li>Which choice uses the least amount of battery or mobile data?</li> +<li>Which choice best supports the design principle +<a href="{@docRoot}design/get-started/principles.html#never-lose-my-stuff">Never lose my stuff</a>?</li> +<li>Which choice best supports the design principle +<a href="{@docRoot}design/get-started/principles.html#interrupt-only-if-important">Only interrupt +me if it's important</a>? +</li> +</ul> + +<h2 id="writing">Writing Guidelines</h2> + +<h4>Label clearly and concisely</h4> + +<p>Writing a good label for a setting can be challenging because space is very limited. You only +get one line, and it's incredibly short on the smallest of devices. Follow these guidelines to +make your labels brief, meaningful, and scannable:</p> + +<ul> +<li>Write each label in sentence case (i.e. only the first word and proper nouns are capitalized). +</li> +<li>Don't start a label with an instructional verb like "Set", "Change", "Edit", "Modify", +"Manage", "Use", "Select", or "Choose". Users already understand that they can do these things to +settings.</li> +<li>Likewise, don't end a label with a word like "setting" or "settings". It's already implied. +</li> +<li>If the setting is part of a grouping, don't repeat the word(s) used in the section divider or +subscreen title.</li> +<li>Avoid starting a label with a negative word like "Don't" or "Never". For example, "Don't +allow" could be rephrased to "Block".</li> +<li>Steer clear of technical jargon as much as possible, unless it's a term widely understood by +your target users. Use common verbs and nouns to convey the setting's purpose rather than its +underlying technology.</li> +<li>Don't refer to the user. For example, for a setting allowing the user to turn notifications on +or off, label it "Notifications" instead of "Notify me".</li> +</ul> + +<p>Once you've decided on labels for your settings, be sure to preview them on an +<a href="{@docRoot}design/style/metrics-grids.html">LDPI handset</a> in portrait to make sure +they'll fit everywhere.</p> + +<h4>Secondary text below is for status, not description…</h4> + +<p>Before Ice Cream Sandwich, we often displayed secondary text below a label to further describe +it or provide instructions. Starting in Ice Cream Sandwich, we're using secondary text for status. +</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <div class="do-dont-label bad emulate-content-left-padding">Before</div> + + <table class="ui-table bad emulate-content-left-padding"> + <thead> + <tr> + <th class="label"> + Screen timeout + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Adjust the delay before the screen automatically turns off + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-4"> + + <div class="do-dont-label good">After</div> + + <table class="ui-table good"> + <thead> + <tr> + <th class="label"> + Sleep + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + After 10 minutes of activity + </td> + </tr> + </tbody> + </table> + + </div> +</div> + +<p>Status in secondary text has the following benefits:</p> +<ul> +<li>Users can see at a glance what the current value of a setting is without having to navigate +any further.</li> +<li>It applies the design principle +<a href="{@docRoot}design/get-started/principles.html#keep-it-brief">Keep it brief</a>, which +users greatly appreciate.</li> +</ul> + +<h4>…unless it's a checkbox setting</h4> +<p>There's one important exception to the using secondary text for status: checkbox settings. +Here, use secondary text for description, not status. Status below a checkbox is unnecessary +because the checkbox already indicates it. The reason why it's appropriate to have a description +below a checkbox setting is because—unlike other controls—it doesn't display a dialog +or navigate to another screen where additional information can be provided.</p> + +<p>That said, if a checkbox setting's label is clear enough on its own, there's no need to also +provide a description. Only include one if necessary.</p> + +<p>Follow these guidelines to write checkbox setting descriptions:</p> +<ul> +<li>Keep it to one sentence and don't use ending punctuation.</li> +<li>Convey what happens when the setting is checked, phrased in the form of a command. Example: +"Allow data exchange", not "Allows data exchange".</li> +<li>Avoid repetition by choosing words that don't already appear in the label.</li> +<li>Don't refer to the user unless it's necessary for understanding the setting.</li> +<li>If you must refer to the user, do so in the second person ("you") rather than the first person +("I"). Android speaks to users, not on behalf of them.</li> +</ul> + +<h4>Writing examples</h4> + +<p>The following are examples of changes we made to labels and secondary text in the Settings app +in Ice Cream Sandwich.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <div class="do-dont-label bad emulate-content-left-padding">Before</div> + + <table class="ui-table bad emulate-content-left-padding"> + <thead> + <tr> + <th class="label"> + Use tactile feedback + </th> + </tr> + </thead> + </table> + + </div> + <div class="layout-content-col span-4"> + + <div class="do-dont-label good">After</div> + + <table class="ui-table good"> + <thead> + <tr> + <th class="label"> + Vibrate on touch + </th> + </tr> + </thead> + </table> + + </div> + <div class="layout-content-col span-5"> + +<p>In this checkbox setting, we eliminated the throwaway word "Use" and rephrased the label to be +more direct and understandable.</p> + + </div> + +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <div class="do-dont-label bad emulate-content-left-padding">Before</div> + + <table class="ui-table bad emulate-content-left-padding"> + <thead> + <tr> + <th class="label"> + Screen timeout + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Adjust the delay before the screen automatically turns off + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-4"> + + <div class="do-dont-label good">After</div> + + <table class="ui-table good"> + <thead> + <tr> + <th class="label"> + Sleep + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + After 10 minutes of activity + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-5"> + +<p>In this multiple choice setting, we changed the label to a friendlier term and also replaced +the description with status. We put some descriptive words around the selected value, "10 +minutes", because on its own, the meaning could be misinterpreted as "sleep for 10 minutes".</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <div class="do-dont-label bad emulate-content-left-padding">Before</div> + + <table class="ui-table bad emulate-content-left-padding"> + <thead> + <tr> + <th class="label"> + Change screen lock + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Change or disable pattern, PIN, or password security + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-4"> + + <div class="do-dont-label good">After</div> + + <table class="ui-table good"> + <thead> + <tr> + <th class="label"> + Screen lock + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Pattern + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-5"> + +<p>This setting navigates to a a sequence of subscreens that allow users to choose a type of +screen lock and then set it up. We eliminated the throwaway word "Change" in the label, and +replaced the description with the current type of screen lock set up by the user. If the user +hasn't set up a screen lock, the secondary text says "None".</p> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <div class="do-dont-label bad emulate-content-left-padding">Before</div> + + <table class="ui-table bad emulate-content-left-padding"> + <thead> + <tr> + <th class="label"> + NFC + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Use Near Field Communication to read and exchange tags + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-4"> + + <div class="do-dont-label good">After</div> + + <table class="ui-table good"> + <thead> + <tr> + <th class="label"> + NFC + </th> + </tr> + </thead> + <tbody> + <tr> + <td class="secondary-text"> + Allow data exchange when the phone touches another device + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-5"> + +<p>In this checkbox setting—although it's technical jargon—we kept the "NFC" label +because: (1) we couldn't find a clear, concise alternative, and (2) user familiarity with the +acronym is expected to increase dramatically in the next couple of years.</p> +<p>We did, however, rewrite the description. It's far less technical than before and does a better +job of conveying how and why you'd use NFC. We didn't include what the acronym stands for because +it doesn't mean anything to most users and would have taken up a lot of space.</p> + + </div> +</div> + +<h2 id="checklist">Checklist</h2> +<ul> +<li><p>Make sure each item in Settings meets the criteria for belonging there.</p></li> +<li><p>If you have more than 7 items, explore ways to group related settings.</p></li> +<li><p>Use design patterns wherever applicable so users don't face a learning curve.</p></li> +<li><p>Choose defaults that are safe, neutral, and fit the majority of users.</p></li> +<li><p>Give each setting a clear, concise label and use secondary text appropriately.</p></li> +</ul>
\ No newline at end of file diff --git a/docs/html/design/patterns/swipe-views.html b/docs/html/design/patterns/swipe-views.html deleted file mode 100644 index 4e8cd03..0000000 --- a/docs/html/design/patterns/swipe-views.html +++ /dev/null @@ -1,225 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Swipe Views - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Swipe Views</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<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 -allow the user to efficiently move from item to item using a simple gesture and thereby make -browsing and consuming data a more fluent experience.</p> -<h2>Swiping Between Detail Views</h2> -<p>An app's data is often organized in a master/detail relationship: The user can view a list of -related data items, such as images, chats, or emails, and then pick one of the items to see the -detail contents in a separate screen.</p> - -<img src="../static/content/swipe_views.png"> -<div class="figure-caption"> - Master (left) and detail (right) views. -</div> - -<p>On a phone, since the master and detail are on separate screens, this typically requires the user to -jump back and forth between the list and the detail view, aka "pogo-sticking".</p> -<p>In cases where users will want to view multiple detail items in succession, avoid pogo-sticking by -using the swipe gesture to navigate to the next/previous detail view.</p> - -<img src="../static/content/swipe_views2.png"> -<div class="figure-caption"> - Navigating between consecutive Email messages using the swipe gesture. -</div> - -<h2>Swiping Between Tabs</h2> - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - - <div class="framed-galaxynexus-port-span-5"> - <video class="play-on-hover" autoplay> - <source src="../static/content/swipe_tabs.mp4" type="video/mp4"> - <source src="../static/content/swipe_tabs.webm" type="video/webm"> - <source src="../static/content/swipe_tabs.ogv" type="video/ogg"> - </video> - </div> - <div class="figure-caption"> - People app with swipe gesture navigation between top-level screens. - <div class="video-instructions"> </div> - </div> - - </div> - <div class="layout-content-col span-8"> - -<p>If your app uses action bar tabs, use swipe to navigate between the different views.</p> -<div class="vspace size-2"> </div> - -<h2>Checklist</h2> -<ul> -<li> -<p>Use swipe to quickly navigate between detail views or tabs.</p> -</li> -<li> -<p>Transition between the views as the user performs the swipe gesture. Do not wait for the - gesture to complete and then transition between views.</p> -</li> -<li> -<p>If you used buttons in the past for previous/next navigation, replace them with - the swipe gesture.</p> -</li> -<li> -<p>Consider adding contextual information in your detail view that informs the user about the - relative list position of the currently visible item.</p> -</li> -</ul> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/patterns/swipe-views.jd b/docs/html/design/patterns/swipe-views.jd new file mode 100644 index 0000000..95d65dd --- /dev/null +++ b/docs/html/design/patterns/swipe-views.jd @@ -0,0 +1,74 @@ +page.title=Swipe Views +@jd:body + +<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 +allow the user to efficiently move from item to item using a simple gesture and thereby make +browsing and consuming data a more fluent experience.</p> +<h2 id="detail-views">Swiping Between Detail Views</h2> + +<p>An app's data is often organized in a master/detail relationship: The user can view a list of +related data items, such as images, chats, or emails, and then pick one of the items to see the +detail contents in a separate screen.</p> + +<img src="{@docRoot}design/media/swipe_views.png"> +<div class="figure-caption"> + Master (left) and detail (right) views. +</div> + +<p>On a phone, since the master and detail are on separate screens, this typically requires the user to +jump back and forth between the list and the detail view, aka "pogo-sticking".</p> +<p>In cases where users will want to view multiple detail items in succession, avoid pogo-sticking by +using the swipe gesture to navigate to the next/previous detail view.</p> + +<img src="{@docRoot}design/media/swipe_views2.png"> +<div class="figure-caption"> + Navigating between consecutive Email messages using the swipe gesture. +</div> + +<h2 id="between-tabs">Swiping Between Tabs</h2> + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + + <div class="framed-galaxynexus-port-span-5"> + <video class="play-on-hover" autoplay> + <source src="{@docRoot}design/media/swipe_tabs.mp4" type="video/mp4"> + <source src="{@docRoot}design/media/swipe_tabs.webm" type="video/webm"> + <source src="{@docRoot}design/media/swipe_tabs.ogv" type="video/ogg"> + </video> + </div> + <div class="figure-caption"> + People app with swipe gesture navigation between top-level screens. + <div class="video-instructions"> </div> + </div> + + </div> + <div class="layout-content-col span-8"> + +<p>If your app uses action bar tabs, use swipe to navigate between the different views.</p> +<div class="vspace size-2"> </div> + +<h2 id="checklist">Checklist</h2> + +<ul> +<li> +<p>Use swipe to quickly navigate between detail views or tabs.</p> +</li> +<li> +<p>Transition between the views as the user performs the swipe gesture. Do not wait for the + gesture to complete and then transition between views.</p> +</li> +<li> +<p>If you used buttons in the past for previous/next navigation, replace them with + the swipe gesture.</p> +</li> +<li> +<p>Consider adding contextual information in your detail view that informs the user about the + relative list position of the currently visible item.</p> +</li> +</ul> + + </div> +</div> diff --git a/docs/html/design/static/callout.png b/docs/html/design/static/callout.png Binary files differdeleted file mode 100644 index 5d49f34..0000000 --- a/docs/html/design/static/callout.png +++ /dev/null diff --git a/docs/html/design/static/content/app_structure_market.png b/docs/html/design/static/content/app_structure_market.png Binary files differdeleted file mode 100644 index 3b0b786..0000000 --- a/docs/html/design/static/content/app_structure_market.png +++ /dev/null diff --git a/docs/html/design/static/content/app_structure_music_lndscp.png b/docs/html/design/static/content/app_structure_music_lndscp.png Binary files differdeleted file mode 100644 index 0dd400c..0000000 --- a/docs/html/design/static/content/app_structure_music_lndscp.png +++ /dev/null diff --git a/docs/html/design/static/content/app_structure_scrolltabs.png b/docs/html/design/static/content/app_structure_scrolltabs.png Binary files differdeleted file mode 100644 index ef4fca4..0000000 --- a/docs/html/design/static/content/app_structure_scrolltabs.png +++ /dev/null diff --git a/docs/html/design/static/content/app_structure_shortcut_on_item.png b/docs/html/design/static/content/app_structure_shortcut_on_item.png Binary files differdeleted file mode 100644 index 3874e1d4..0000000 --- a/docs/html/design/static/content/app_structure_shortcut_on_item.png +++ /dev/null diff --git a/docs/html/design/static/content/iconography_launcher_example.png b/docs/html/design/static/content/iconography_launcher_example.png Binary files differdeleted file mode 100644 index a5db53e..0000000 --- a/docs/html/design/static/content/iconography_launcher_example.png +++ /dev/null diff --git a/docs/html/design/static/content/iconography_overview.png b/docs/html/design/static/content/iconography_overview.png Binary files differdeleted file mode 100644 index 688c1b5..0000000 --- a/docs/html/design/static/content/iconography_overview.png +++ /dev/null diff --git a/docs/html/design/static/content/misc_full_galaxynexus_blank_land_span13.png b/docs/html/design/static/content/misc_full_galaxynexus_blank_land_span13.png Binary files differdeleted file mode 100644 index bab6aca..0000000 --- a/docs/html/design/static/content/misc_full_galaxynexus_blank_land_span13.png +++ /dev/null diff --git a/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span5.png b/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span5.png Binary files differdeleted file mode 100644 index bdccc2f..0000000 --- a/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span5.png +++ /dev/null diff --git a/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span9.png b/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span9.png Binary files differdeleted file mode 100644 index 5e0135b..0000000 --- a/docs/html/design/static/content/misc_full_galaxynexus_blank_port_span9.png +++ /dev/null diff --git a/docs/html/design/static/content/navigation_between_siblings_market1.png b/docs/html/design/static/content/navigation_between_siblings_market1.png Binary files differdeleted file mode 100644 index c3148f8..0000000 --- a/docs/html/design/static/content/navigation_between_siblings_market1.png +++ /dev/null diff --git a/docs/html/design/static/content/navigation_between_siblings_market2.png b/docs/html/design/static/content/navigation_between_siblings_market2.png Binary files differdeleted file mode 100644 index 208be47..0000000 --- a/docs/html/design/static/content/navigation_between_siblings_market2.png +++ /dev/null diff --git a/docs/html/design/static/content/navigation_from_outside_up.png b/docs/html/design/static/content/navigation_from_outside_up.png Binary files differdeleted file mode 100644 index eaa3cdb..0000000 --- a/docs/html/design/static/content/navigation_from_outside_up.png +++ /dev/null diff --git a/docs/html/design/static/content/navigation_up_vs_back_gmail.png b/docs/html/design/static/content/navigation_up_vs_back_gmail.png Binary files differdeleted file mode 100644 index 71e6484..0000000 --- a/docs/html/design/static/content/navigation_up_vs_back_gmail.png +++ /dev/null diff --git a/docs/html/design/static/content/navigation_with_back_and_up.png b/docs/html/design/static/content/navigation_with_back_and_up.png Binary files differdeleted file mode 100644 index 4fb6dce..0000000 --- a/docs/html/design/static/content/navigation_with_back_and_up.png +++ /dev/null diff --git a/docs/html/design/static/content/progress_activity.png b/docs/html/design/static/content/progress_activity.png Binary files differdeleted file mode 100644 index 51210b4..0000000 --- a/docs/html/design/static/content/progress_activity.png +++ /dev/null diff --git a/docs/html/design/static/content/progress_download.png b/docs/html/design/static/content/progress_download.png Binary files differdeleted file mode 100644 index f567f74..0000000 --- a/docs/html/design/static/content/progress_download.png +++ /dev/null diff --git a/docs/html/design/static/content/tabs_scrolly.mp4 b/docs/html/design/static/content/tabs_scrolly.mp4 Binary files differdeleted file mode 100644 index 4329243..0000000 --- a/docs/html/design/static/content/tabs_scrolly.mp4 +++ /dev/null diff --git a/docs/html/design/static/content/tabs_scrolly.ogv b/docs/html/design/static/content/tabs_scrolly.ogv Binary files differdeleted file mode 100644 index 345e57a..0000000 --- a/docs/html/design/static/content/tabs_scrolly.ogv +++ /dev/null diff --git a/docs/html/design/static/content/tabs_scrolly.webm b/docs/html/design/static/content/tabs_scrolly.webm Binary files differdeleted file mode 100644 index 17e368e..0000000 --- a/docs/html/design/static/content/tabs_scrolly.webm +++ /dev/null diff --git a/docs/html/design/static/content/ui_overview_all_apps.png b/docs/html/design/static/content/ui_overview_all_apps.png Binary files differdeleted file mode 100644 index 467f5ad..0000000 --- a/docs/html/design/static/content/ui_overview_all_apps.png +++ /dev/null diff --git a/docs/html/design/static/default.css b/docs/html/design/static/default.css deleted file mode 100644 index 42ab527..0000000 --- a/docs/html/design/static/default.css +++ /dev/null @@ -1,571 +0,0 @@ -/* color definitions */ -/* 16 column layout */ -/* clearfix idiom */ -/* common mixins */ -/* page layout + top-level styles */ -::-moz-selection, -::-webkit-selection, -::selection { - background-color: #0099cc; - color: #fff; } - -html, body { - height: 100%; - margin: 0; - padding: 0; - background: #eee none no-repeat fixed top left; - background-image: -webkit-gradient(linear, 100% 0%, 100% 100%, from(#dddddd), color-stop(25%, #f2f2f2), color-stop(75%, #f2f2f2), to(#dddddd)); - background-image: -moz-linear-gradient(top, #dddddd, #f2f2f2, #f2f2f2, #dddddd); - -webkit-font-smoothing: antialiased; - /* prevent subpixel antialiasing, which thickens the text */ - text-rendering: optimizeLegibility; - /* opentype ftw */ } - -body { - color: #555555; - font: 14px/20px Roboto, sans-serif; - font-weight: 400; } - -#page-container { - width: 940px; - margin: 0 40px; } - -#page-header { - height: 80px; - margin-bottom: 20px; - font-size: 48px; - line-height: 48px; - font-weight: 100; - padding-left: 10px; } - #page-header a { - display: block; - position: relative; - top: 20px; - text-decoration: none; - color: #555555 !important; } - -#main-row { - display: inline-block; } - #main-row:after { - content: "."; - display: block; - height: 0; - clear: both; - visibility: hidden; } - * html #main-row { - height: 1px; } - -#page-footer { - margin-left: 190px; - margin-top: 80px; - color: #999999; - padding-bottom: 40px; - font-size: 12px; - line-height: 15px; } - #page-footer a { - color: #777777; } - #page-footer #copyright { - margin-bottom: 10px; } - -#nav { - width: 160px; - margin-right: 20px; - float: left; } - -#content { - width: 760px; - float: left; } - -a, -a:visited { - color: #333333; } - -a:hover, -acronym:hover { - color: #7aa1b0 !important; } - -a:focus, -a:active { - color: #33b5e5 !important; } - -img { - border: none; } - -ul { - margin: 0; - padding: 0; } - -strong { - font-weight: 500; } - -em { - font-style: italic; } - -code { - font-family: Courier New, monospace; } - -acronym { - border-bottom: 1px dotted #555555; - cursor: help; } - -acronym:hover { - border-bottom-color: #7aa1b0; } - -img.with-shadow, -video.with-shadow { - box-shadow: 0 2px 4px rgba(0, 0, 0, 0.25); } - -/* disclosures mixin */ -/* content layout */ -.layout-content-row { - display: inline-block; - margin-bottom: 10px; } - .layout-content-row:after { - content: "."; - display: block; - height: 0; - clear: both; - visibility: hidden; } - * html .layout-content-row { - height: 1px; } - -.layout-content-col { - float: left; - margin-left: 20px; } - .layout-content-col:first-child { - margin-left: 0; } - -.layout-content-col.span-1 { - width: 40px; } - -.layout-content-col.span-2 { - width: 100px; } - -.layout-content-col.span-3 { - width: 160px; } - -.layout-content-col.span-4 { - width: 220px; } - -.layout-content-col.span-5 { - width: 280px; } - -.layout-content-col.span-6 { - width: 340px; } - -.layout-content-col.span-7 { - width: 400px; } - -.layout-content-col.span-8 { - width: 460px; } - -.layout-content-col.span-9 { - width: 520px; } - -.layout-content-col.span-10 { - width: 580px; } - -.layout-content-col.span-11 { - width: 640px; } - -.layout-content-col.span-12 { - width: 700px; } - -.layout-content-col.span-13 { - width: 760px; } - -.vspace.size-1 { - height: 10px; } - -.vspace.size-2 { - height: 20px; } - -.vspace.size-3 { - height: 30px; } - -.vspace.size-4 { - height: 40px; } - -.vspace.size-5 { - height: 50px; } - -.vspace.size-6 { - height: 60px; } - -.vspace.size-7 { - height: 70px; } - -.vspace.size-8 { - height: 80px; } - -.vspace.size-9 { - height: 90px; } - -.vspace.size-10 { - height: 100px; } - -.vspace.size-11 { - height: 110px; } - -.vspace.size-12 { - height: 120px; } - -.vspace.size-13 { - height: 130px; } - -.vspace.size-14 { - height: 140px; } - -.vspace.size-15 { - height: 150px; } - -.vspace.size-16 { - height: 160px; } - -/* nav */ -#nav { - /* section header divs */ - /* expanded section header divs */ - /* sublinks */ } - #nav li { - list-style-type: none; - font-size: 14px; - line-height: 10px; } - #nav a { - color: #555555; - text-decoration: none; } - #nav li.selected > a, - #nav li.selected .nav-section-header a { - font-weight: 500; - color: #0099cc !important; } - #nav .nav-section-header { - position: relative; - padding: 10px; - margin-bottom: 1px; - /* section header links */ } - #nav .nav-section-header a { - color: #333333; - font-weight: 500; - text-transform: uppercase; } - #nav .nav-section-header:after { - content: ''; - background: transparent url(disclosure_down.png) no-repeat scroll top left; - width: 10px; - height: 10px; - display: block; - position: absolute; - top: 10px; - right: 10px; } - #nav li.expanded .nav-section-header { - background: rgba(0, 0, 0, 0.05); } - #nav li.expanded .nav-section-header:after { - content: ''; - background: transparent url(disclosure_up.png) no-repeat scroll top left; - width: 10px; - height: 10px; } - #nav > li > ul { - height: 0; - overflow: hidden; - margin-bottom: 0; } - #nav > li > ul.animate-height { - transition: height 0.25s ease-in; - -webkit-transition: height 0.25s ease-in; - -moz-transition: height 0.25s ease-in; } - #nav > li > ul li { - padding: 10px 10px 11px 10px; } - #nav > li.expanded > ul { - height: auto; } - #nav > li.expanded > ul li { - background: rgba(0, 0, 0, 0.03); } - #nav #back-dac-section { - padding: 10px; - border-top: 1px solid #ddd; } - #nav #back-dac-section a { - color: #333333; - font-weight: 500; - text-transform: uppercase; } - -/* content header */ -.content-header { - border-bottom: 1px solid #33b5e5; - height: 30px; } - .content-header h2 { - border-bottom: 0; } - .content-header.just-links { - border-bottom: 0; } - -.content-footer { - border-top: 1px solid #33b5e5; - margin-top: 10px; - height: 30px; } - -.paging-links { - position: relative; } - .paging-links a { - position: absolute; - font-size: 14px; - line-height: 30px; - color: #555555; - text-decoration: none; - text-transform: uppercase; } - .paging-links .prev-page-link { - display: none; - left: -5px; } - .paging-links .prev-page-link:before { - content: ''; - background: transparent url(disclosure_left.png) no-repeat scroll top left; - width: 10px; - height: 10px; - display: inline-block; - margin-right: 5px; } - .paging-links .next-page-link { - display: none; - right: 10px; } - .paging-links .next-page-link:after { - content: ''; - background: transparent url(disclosure_right.png) no-repeat scroll top left; - width: 10px; - height: 10px; - display: inline-block; - margin-left: 5px; } - -/* content body */ -#content p, -#content ul, -#content ol, -#content h3 { - margin: 0 10px 10px 10px; } -#content h2 { - padding-left: 10px; - padding-right: 10px; - margin-bottom: 10px; - font-size: 16px; - line-height: 30px; - font-weight: 500; - color: #33b5e5; - border-bottom: 1px solid #33b5e5; - height: 30px; } -#content hr { - border: 0; - border-bottom: 1px solid #33b5e5; - margin-bottom: 20px; } -#content h3 { - color: #33b5e5; - text-transform: uppercase; - font-size: 14px; - line-height: 20px; - font-weight: 500; } -#content h4 { - margin: 0 10px; - color: #333333; - font-weight: 500; - font-size: 14px; - line-height: 20px; } -#content strong { - color: #333333; } -#content ul li, -#content ol li { - margin-left: 20px; } - #content ul li h4, - #content ol li h4 { - margin: 0; } - #content ul li p, - #content ol li p { - margin-left: 0; } -#content ul li { - list-style-type: square; - list-style-type: none; - position: relative; } - #content ul li:before { - content: '\2022'; - font-family: verdana; - font-size: 14px; - line-height: 20px; - position: absolute; - left: -20px; - top: -1px; } -#content ol { - counter-reset: item; } - #content ol li { - font-size: 14px; - line-height: 20px; - list-style-type: none; - position: relative; } - #content ol li:before { - content: counter(item) ". "; - counter-increment: item; - position: absolute; - left: -20px; - top: 0; } - #content ol li.value-1:before { - content: "1. "; } - #content ol li.value-2:before { - content: "2. "; } - #content ol li.value-3:before { - content: "3. "; } - #content ol li.value-4:before { - content: "4. "; } - #content ol li.value-5:before { - content: "5. "; } - #content ol li.value-6:before { - content: "6. "; } - #content ol li.value-7:before { - content: "7. "; } - #content ol li.value-8:before { - content: "8. "; } - #content ol li.value-9:before { - content: "9. "; } - #content ol li.value-10:before { - content: "10. "; } -#content .with-callouts ol li { - list-style-position: inside; - margin-left: 0; } - #content .with-callouts ol li:before { - position: static; - display: inline; - left: 0; - float: left; - width: 17px; - color: #33b5e5; - font-weight: 500; } - -/* special list items */ -li.no-bullet { - list-style-type: none !important; } - -#content li.with-icon { - position: relative; - margin-left: 40px; - min-height: 30px; } - #content li.with-icon p { - margin-left: 0 !important; } - #content li.with-icon:before { - position: absolute; - left: -40px; - top: 0; - content: ''; - width: 30px; - height: 30px; } - #content li.with-icon.tablet:before { - background-image: url(ico_phone_tablet.png); } - #content li.with-icon.web:before { - background-image: url(ico_web.png); } - #content li.with-icon.checklist:before { - background-image: url(ico_checklist.png); } - #content li.with-icon.action:before { - background-image: url(ico_action.png); } - #content li.with-icon.use:before { - background-image: url(ico_use.png); } - -/* figures and callouts */ -.figure { - position: relative; } - .figure.pad-below { - margin-bottom: 20px; } - .figure .figure-callout { - position: absolute; - color: #fff; - font-weight: 500; - font-size: 16px; - line-height: 23px; - text-align: center; - background: transparent url(callout.png) no-repeat scroll 50% 50%; - padding-right: 2px; - width: 30px; - height: 29px; - z-index: 1000; } - .figure .figure-callout.top { - top: -9px; } - .figure .figure-callout.right { - right: -5px; } - -.figure-caption { - margin: 0 10px 20px 10px; - font-size: 14px; - line-height: 20px; - font-style: italic; } - -/* rows of figures */ -.figure-row { - font-size: 0; - line-height: 0; - /* to prevent space between figures */ } - .figure-row .figure { - display: inline-block; - vertical-align: top; } - .figure-row .figure + .figure { - margin-left: 10px; - /* reintroduce space between figures */ } - -/* video containers */ -.framed-galaxynexus-land-span-13 { - background: transparent url(content/misc_full_galaxynexus_blank_land_span13.png) no-repeat scroll top left; - padding: 42px 122px 62px 126px; - overflow: hidden; } - .framed-galaxynexus-land-span-13, .framed-galaxynexus-land-span-13 video, .framed-galaxynexus-land-span-13 img { - width: 512px; - height: 286px; } - -.framed-galaxynexus-port-span-9 { - background: transparent url(content/misc_full_galaxynexus_blank_port_span9.png) no-repeat scroll top left; - padding: 95px 122px 107px 124px; - overflow: hidden; } - .framed-galaxynexus-port-span-9, .framed-galaxynexus-port-span-9 video, .framed-galaxynexus-port-span-9 img { - width: 274px; - height: 488px; } - -.framed-galaxynexus-port-span-5 { - background: transparent url(content/misc_full_galaxynexus_blank_port_span5.png) no-repeat scroll top left; - padding: 75px 31px 76px 33px; - overflow: hidden; } - .framed-galaxynexus-port-span-5, .framed-galaxynexus-port-span-5 video, .framed-galaxynexus-port-span-5 img { - width: 216px; - height: 384px; } - -/* landing page disclosures */ -.landing-page-link { - text-decoration: none; - font-weight: 500; - color: #333333; } - .landing-page-link:after { - content: ''; - background: transparent url(disclosure_right.png) no-repeat scroll top left; - width: 10px; - height: 10px; - display: inline-block; - margin-left: 5px; } - -/* tooltips */ -.tooltip-box { - position: absolute; - background-color: rgba(0, 0, 0, 0.9); - border-radius: 2px; - font-size: 14px; - line-height: 20px; - color: #fff; - padding: 6px 10px; - max-width: 250px; - z-index: 10000; } - .tooltip-box.below:after { - position: absolute; - content: ''; - line-height: 0; - display: block; - top: -10px; - left: 5px; - border: 5px solid transparent; - border-bottom-color: rgba(0, 0, 0, 0.9); } - -/* video note */ -.video-instructions { - margin-top: 10px; - margin-bottom: 10px; } - .video-instructions:before { - content: ''; - background: transparent url(ico_movie_inline.png) no-repeat scroll top left; - display: inline-block; - width: 12px; - height: 12px; - margin-right: 8px; } - .video-instructions:after { - content: 'Click to replay movie.'; } diff --git a/docs/html/design/static/default.js b/docs/html/design/static/default.js deleted file mode 100644 index 6721ab8..0000000 --- a/docs/html/design/static/default.js +++ /dev/null @@ -1,161 +0,0 @@ -$(document).ready(function() { - // prep nav expandos - var pagePath = document.location.pathname; - if (pagePath.indexOf(SITE_ROOT) == 0) { - pagePath = pagePath.substr(SITE_ROOT.length); - if (pagePath == '' || pagePath.charAt(pagePath.length - 1) == '/') { - pagePath += 'index.html'; - } - } - - if (SITE_ROOT.match(/\.\.\//) || SITE_ROOT == '') { - // If running locally, SITE_ROOT will be a relative path, so account for that by - // finding the relative URL to this page. This will allow us to find links on the page - // leading back to this page. - var pathParts = pagePath.split('/'); - var relativePagePathParts = []; - var upDirs = (SITE_ROOT.match(/(\.\.\/)+/) || [''])[0].length / 3; - for (var i = 0; i < upDirs; i++) { - relativePagePathParts.push('..'); - } - for (var i = 0; i < upDirs; i++) { - relativePagePathParts.push(pathParts[pathParts.length - (upDirs - i) - 1]); - } - relativePagePathParts.push(pathParts[pathParts.length - 1]); - pagePath = relativePagePathParts.join('/'); - } else { - // Otherwise the page path should be an absolute URL. - pagePath = SITE_ROOT + pagePath; - } - - // select current page in sidenav and set up prev/next links if they exist - var $selNavLink = $('#nav').find('a[href="' + pagePath + '"]'); - if ($selNavLink.length) { - $selListItem = $selNavLink.closest('li'); - - $selListItem.addClass('selected'); - $selListItem.closest('li.nav-section').addClass('expanded'); - - // set up prev links - var $prevLink = []; - var $prevListItem = $selListItem.prev('li'); - if ($prevListItem.length) { - if ($prevListItem.hasClass('nav-section')) { - // jump to last topic of previous section - $prevLink = $prevListItem.find('a:last'); - } else { - // jump to previous topic in this section - $prevLink = $prevListItem.find('a:eq(0)'); - } - } else { - // jump to this section's index page (if it exists) - $prevLink = $selListItem.parents('li').find('a'); - } - - if ($prevLink.length) { - var prevHref = $prevLink.attr('href'); - if (prevHref == SITE_ROOT + 'index.html') { - // Don't show Previous when it leads to the homepage - $('.prev-page-link').hide(); - } else { - $('.prev-page-link').attr('href', prevHref).show(); - } - } else { - $('.prev-page-link').hide(); - } - - // set up next links - var $nextLink = []; - if ($selListItem.hasClass('nav-section')) { - // we're on an index page, jump to the first topic - $nextLink = $selListItem.find('ul').find('a:eq(0)') - } else { - // jump to the next topic in this section (if it exists) - $nextLink = $selListItem.next('li').find('a:eq(0)'); - if (!$nextLink.length) { - // no more topics in this section, jump to the first topic in the next section - $nextLink = $selListItem.parents('li').next('li.nav-section').find('a:eq(0)'); - } - } - if ($nextLink.length) { - $('.next-page-link').attr('href', $nextLink.attr('href')).show(); - } else { - $('.next-page-link').hide(); - } - } - - // Set up expand/collapse behavior - $('#nav li.nav-section').click(function() { - if ($(this).hasClass('expanded')) { - return; - } - - // hide other - var $old = $('#nav li.nav-section.expanded'); - if ($old.length) { - var $oldUl = $old.children('ul'); - $oldUl.css('height', $oldUl.height() + 'px'); - window.setTimeout(function() { - $oldUl - .addClass('animate-height') - .css('height', ''); - }, 0); - $old.removeClass('expanded'); - } - - // show me - $(this).addClass('expanded'); - var $ul = $(this).children('ul'); - var expandedHeight = $ul.height(); - $ul - .removeClass('animate-height') - .css('height', 0); - window.setTimeout(function() { - $ul - .addClass('animate-height') - .css('height', expandedHeight + 'px'); - }, 0); - }); - - // Stop expand/collapse behavior when clicking on nav section links (since we're navigating away - // from the page) - $('.nav-section-header').find('a:eq(0)').click(function(evt) { - window.location.href = $(this).attr('href'); - return false; - }); - - // Set up play-on-hover <video> tags. - $('video.play-on-hover').bind('click', function(){ - $(this).get(0).load(); // in case the video isn't seekable - $(this).get(0).play(); - }); - - // Set up tooltips - var TOOLTIP_MARGIN = 10; - $('acronym').each(function() { - var $target = $(this); - var $tooltip = $('<div>') - .addClass('tooltip-box') - .text($target.attr('title')) - .hide() - .appendTo('body'); - $target.removeAttr('title'); - - $target.hover(function() { - // in - var targetRect = $target.offset(); - targetRect.width = $target.width(); - targetRect.height = $target.height(); - - $tooltip.css({ - left: targetRect.left, - top: targetRect.top + targetRect.height + TOOLTIP_MARGIN - }); - $tooltip.addClass('below'); - $tooltip.show(); - }, function() { - // out - $tooltip.hide(); - }); - }); -});
\ No newline at end of file diff --git a/docs/html/design/static/disclosure_down.png b/docs/html/design/static/disclosure_down.png Binary files differdeleted file mode 100644 index 4b3ff4d..0000000 --- a/docs/html/design/static/disclosure_down.png +++ /dev/null diff --git a/docs/html/design/static/disclosure_left.png b/docs/html/design/static/disclosure_left.png Binary files differdeleted file mode 100644 index 607845e..0000000 --- a/docs/html/design/static/disclosure_left.png +++ /dev/null diff --git a/docs/html/design/static/disclosure_right.png b/docs/html/design/static/disclosure_right.png Binary files differdeleted file mode 100644 index f3bceb1..0000000 --- a/docs/html/design/static/disclosure_right.png +++ /dev/null diff --git a/docs/html/design/static/disclosure_up.png b/docs/html/design/static/disclosure_up.png Binary files differdeleted file mode 100644 index 5ff6d9d..0000000 --- a/docs/html/design/static/disclosure_up.png +++ /dev/null diff --git a/docs/html/design/static/download/RobotoSpecimenBook.pdf b/docs/html/design/static/download/RobotoSpecimenBook.pdf Binary files differdeleted file mode 100644 index 594a366..0000000 --- a/docs/html/design/static/download/RobotoSpecimenBook.pdf +++ /dev/null diff --git a/docs/html/design/static/download/Roboto_Hinted_20111129.zip b/docs/html/design/static/download/Roboto_Hinted_20111129.zip Binary files differdeleted file mode 100644 index 3d3ab77..0000000 --- a/docs/html/design/static/download/Roboto_Hinted_20111129.zip +++ /dev/null diff --git a/docs/html/design/static/download/action_bar_icons-v4.0.zip b/docs/html/design/static/download/action_bar_icons-v4.0.zip Binary files differdeleted file mode 100644 index 4568894..0000000 --- a/docs/html/design/static/download/action_bar_icons-v4.0.zip +++ /dev/null diff --git a/docs/html/design/static/download/color_swatches.zip b/docs/html/design/static/download/color_swatches.zip Binary files differdeleted file mode 100644 index 0221d7b..0000000 --- a/docs/html/design/static/download/color_swatches.zip +++ /dev/null diff --git a/docs/html/design/static/ico_action.png b/docs/html/design/static/ico_action.png Binary files differdeleted file mode 100644 index 30e4cc7..0000000 --- a/docs/html/design/static/ico_action.png +++ /dev/null diff --git a/docs/html/design/static/ico_good.png b/docs/html/design/static/ico_good.png Binary files differdeleted file mode 100644 index afebe1c..0000000 --- a/docs/html/design/static/ico_good.png +++ /dev/null diff --git a/docs/html/design/static/ico_movie_inline.png b/docs/html/design/static/ico_movie_inline.png Binary files differdeleted file mode 100644 index 7cfb5c5..0000000 --- a/docs/html/design/static/ico_movie_inline.png +++ /dev/null diff --git a/docs/html/design/static/ico_phone_tablet.png b/docs/html/design/static/ico_phone_tablet.png Binary files differdeleted file mode 100644 index 003b876..0000000 --- a/docs/html/design/static/ico_phone_tablet.png +++ /dev/null diff --git a/docs/html/design/static/ico_styleguide.png b/docs/html/design/static/ico_styleguide.png Binary files differdeleted file mode 100644 index c12907c..0000000 --- a/docs/html/design/static/ico_styleguide.png +++ /dev/null diff --git a/docs/html/design/static/ico_use.png b/docs/html/design/static/ico_use.png Binary files differdeleted file mode 100644 index 9d868b3..0000000 --- a/docs/html/design/static/ico_use.png +++ /dev/null diff --git a/docs/html/design/static/ico_web.png b/docs/html/design/static/ico_web.png Binary files differdeleted file mode 100644 index 0848e3c..0000000 --- a/docs/html/design/static/ico_web.png +++ /dev/null diff --git a/docs/html/design/static/ico_wrong.png b/docs/html/design/static/ico_wrong.png Binary files differdeleted file mode 100644 index b7d04ce..0000000 --- a/docs/html/design/static/ico_wrong.png +++ /dev/null diff --git a/docs/html/design/static/jquery-1.6.2.min.js b/docs/html/design/static/jquery-1.6.2.min.js deleted file mode 100644 index 8cdc80e..0000000 --- a/docs/html/design/static/jquery-1.6.2.min.js +++ /dev/null @@ -1,18 +0,0 @@ -/*! - * jQuery JavaScript Library v1.6.2 - * http://jquery.com/ - * - * Copyright 2011, John Resig - * Dual licensed under the MIT or GPL Version 2 licenses. - * http://jquery.org/license - * - * Includes Sizzle.js - * http://sizzlejs.com/ - * Copyright 2011, The Dojo Foundation - * Released under the MIT, BSD, and GPL Licenses. - * - * Date: Thu Jun 30 14:16:56 2011 -0400 - */ -(function(a,b){function cv(a){return f.isWindow(a)?a:a.nodeType===9?a.defaultView||a.parentWindow:!1}function cs(a){if(!cg[a]){var b=c.body,d=f("<"+a+">").appendTo(b),e=d.css("display");d.remove();if(e==="none"||e===""){ch||(ch=c.createElement("iframe"),ch.frameBorder=ch.width=ch.height=0),b.appendChild(ch);if(!ci||!ch.createElement)ci=(ch.contentWindow||ch.contentDocument).document,ci.write((c.compatMode==="CSS1Compat"?"<!doctype html>":"")+"<html><body>"),ci.close();d=ci.createElement(a),ci.body.appendChild(d),e=f.css(d,"display"),b.removeChild(ch)}cg[a]=e}return cg[a]}function cr(a,b){var c={};f.each(cm.concat.apply([],cm.slice(0,b)),function(){c[this]=a});return c}function cq(){cn=b}function cp(){setTimeout(cq,0);return cn=f.now()}function cf(){try{return new a.ActiveXObject("Microsoft.XMLHTTP")}catch(b){}}function ce(){try{return new a.XMLHttpRequest}catch(b){}}function b$(a,c){a.dataFilter&&(c=a.dataFilter(c,a.dataType));var d=a.dataTypes,e={},g,h,i=d.length,j,k=d[0],l,m,n,o,p;for(g=1;g<i;g++){if(g===1)for(h in a.converters)typeof h=="string"&&(e[h.toLowerCase()]=a.converters[h]);l=k,k=d[g];if(k==="*")k=l;else if(l!=="*"&&l!==k){m=l+" "+k,n=e[m]||e["* "+k];if(!n){p=b;for(o in e){j=o.split(" ");if(j[0]===l||j[0]==="*"){p=e[j[1]+" "+k];if(p){o=e[o],o===!0?n=p:p===!0&&(n=o);break}}}}!n&&!p&&f.error("No conversion from "+m.replace(" "," to ")),n!==!0&&(c=n?n(c):p(o(c)))}}return c}function bZ(a,c,d){var e=a.contents,f=a.dataTypes,g=a.responseFields,h,i,j,k;for(i in g)i in d&&(c[g[i]]=d[i]);while(f[0]==="*")f.shift(),h===b&&(h=a.mimeType||c.getResponseHeader("content-type"));if(h)for(i in e)if(e[i]&&e[i].test(h)){f.unshift(i);break}if(f[0]in d)j=f[0];else{for(i in d){if(!f[0]||a.converters[i+" "+f[0]]){j=i;break}k||(k=i)}j=j||k}if(j){j!==f[0]&&f.unshift(j);return d[j]}}function bY(a,b,c,d){if(f.isArray(b))f.each(b,function(b,e){c||bC.test(a)?d(a,e):bY(a+"["+(typeof e=="object"||f.isArray(e)?b:"")+"]",e,c,d)});else if(!c&&b!=null&&typeof b=="object")for(var e in b)bY(a+"["+e+"]",b[e],c,d);else d(a,b)}function bX(a,c,d,e,f,g){f=f||c.dataTypes[0],g=g||{},g[f]=!0;var h=a[f],i=0,j=h?h.length:0,k=a===bR,l;for(;i<j&&(k||!l);i++)l=h[i](c,d,e),typeof l=="string"&&(!k||g[l]?l=b:(c.dataTypes.unshift(l),l=bX(a,c,d,e,l,g)));(k||!l)&&!g["*"]&&(l=bX(a,c,d,e,"*",g));return l}function bW(a){return function(b,c){typeof b!="string"&&(c=b,b="*");if(f.isFunction(c)){var d=b.toLowerCase().split(bN),e=0,g=d.length,h,i,j;for(;e<g;e++)h=d[e],j=/^\+/.test(h),j&&(h=h.substr(1)||"*"),i=a[h]=a[h]||[],i[j?"unshift":"push"](c)}}}function bA(a,b,c){var d=b==="width"?a.offsetWidth:a.offsetHeight,e=b==="width"?bv:bw;if(d>0){c!=="border"&&f.each(e,function(){c||(d-=parseFloat(f.css(a,"padding"+this))||0),c==="margin"?d+=parseFloat(f.css(a,c+this))||0:d-=parseFloat(f.css(a,"border"+this+"Width"))||0});return d+"px"}d=bx(a,b,b);if(d<0||d==null)d=a.style[b]||0;d=parseFloat(d)||0,c&&f.each(e,function(){d+=parseFloat(f.css(a,"padding"+this))||0,c!=="padding"&&(d+=parseFloat(f.css(a,"border"+this+"Width"))||0),c==="margin"&&(d+=parseFloat(f.css(a,c+this))||0)});return d+"px"}function bm(a,b){b.src?f.ajax({url:b.src,async:!1,dataType:"script"}):f.globalEval((b.text||b.textContent||b.innerHTML||"").replace(be,"/*$0*/")),b.parentNode&&b.parentNode.removeChild(b)}function bl(a){f.nodeName(a,"input")?bk(a):"getElementsByTagName"in a&&f.grep(a.getElementsByTagName("input"),bk)}function bk(a){if(a.type==="checkbox"||a.type==="radio")a.defaultChecked=a.checked}function bj(a){return"getElementsByTagName"in a?a.getElementsByTagName("*"):"querySelectorAll"in a?a.querySelectorAll("*"):[]}function bi(a,b){var c;if(b.nodeType===1){b.clearAttributes&&b.clearAttributes(),b.mergeAttributes&&b.mergeAttributes(a),c=b.nodeName.toLowerCase();if(c==="object")b.outerHTML=a.outerHTML;else if(c!=="input"||a.type!=="checkbox"&&a.type!=="radio"){if(c==="option")b.selected=a.defaultSelected;else if(c==="input"||c==="textarea")b.defaultValue=a.defaultValue}else a.checked&&(b.defaultChecked=b.checked=a.checked),b.value!==a.value&&(b.value=a.value);b.removeAttribute(f.expando)}}function bh(a,b){if(b.nodeType===1&&!!f.hasData(a)){var c=f.expando,d=f.data(a),e=f.data(b,d);if(d=d[c]){var g=d.events;e=e[c]=f.extend({},d);if(g){delete e.handle,e.events={};for(var h in g)for(var i=0,j=g[h].length;i<j;i++)f.event.add(b,h+(g[h][i].namespace?".":"")+g[h][i].namespace,g[h][i],g[h][i].data)}}}}function bg(a,b){return f.nodeName(a,"table")?a.getElementsByTagName("tbody")[0]||a.appendChild(a.ownerDocument.createElement("tbody")):a}function W(a,b,c){b=b||0;if(f.isFunction(b))return f.grep(a,function(a,d){var e=!!b.call(a,d,a);return e===c});if(b.nodeType)return f.grep(a,function(a,d){return a===b===c});if(typeof b=="string"){var d=f.grep(a,function(a){return a.nodeType===1});if(R.test(b))return f.filter(b,d,!c);b=f.filter(b,d)}return f.grep(a,function(a,d){return f.inArray(a,b)>=0===c})}function V(a){return!a||!a.parentNode||a.parentNode.nodeType===11}function N(a,b){return(a&&a!=="*"?a+".":"")+b.replace(z,"`").replace(A,"&")}function M(a){var b,c,d,e,g,h,i,j,k,l,m,n,o,p=[],q=[],r=f._data(this,"events");if(!(a.liveFired===this||!r||!r.live||a.target.disabled||a.button&&a.type==="click")){a.namespace&&(n=new RegExp("(^|\\.)"+a.namespace.split(".").join("\\.(?:.*\\.)?")+"(\\.|$)")),a.liveFired=this;var s=r.live.slice(0);for(i=0;i<s.length;i++)g=s[i],g.origType.replace(x,"")===a.type?q.push(g.selector):s.splice(i--,1);e=f(a.target).closest(q,a.currentTarget);for(j=0,k=e.length;j<k;j++){m=e[j];for(i=0;i<s.length;i++){g=s[i];if(m.selector===g.selector&&(!n||n.test(g.namespace))&&!m.elem.disabled){h=m.elem,d=null;if(g.preType==="mouseenter"||g.preType==="mouseleave")a.type=g.preType,d=f(a.relatedTarget).closest(g.selector)[0],d&&f.contains(h,d)&&(d=h);(!d||d!==h)&&p.push({elem:h,handleObj:g,level:m.level})}}}for(j=0,k=p.length;j<k;j++){e=p[j];if(c&&e.level>c)break;a.currentTarget=e.elem,a.data=e.handleObj.data,a.handleObj=e.handleObj,o=e.handleObj.origHandler.apply(e.elem,arguments);if(o===!1||a.isPropagationStopped()){c=e.level,o===!1&&(b=!1);if(a.isImmediatePropagationStopped())break}}return b}}function K(a,c,d){var e=f.extend({},d[0]);e.type=a,e.originalEvent={},e.liveFired=b,f.event.handle.call(c,e),e.isDefaultPrevented()&&d[0].preventDefault()}function E(){return!0}function D(){return!1}function m(a,c,d){var e=c+"defer",g=c+"queue",h=c+"mark",i=f.data(a,e,b,!0);i&&(d==="queue"||!f.data(a,g,b,!0))&&(d==="mark"||!f.data(a,h,b,!0))&&setTimeout(function(){!f.data(a,g,b,!0)&&!f.data(a,h,b,!0)&&(f.removeData(a,e,!0),i.resolve())},0)}function l(a){for(var b in a)if(b!=="toJSON")return!1;return!0}function k(a,c,d){if(d===b&&a.nodeType===1){var e="data-"+c.replace(j,"$1-$2").toLowerCase();d=a.getAttribute(e);if(typeof d=="string"){try{d=d==="true"?!0:d==="false"?!1:d==="null"?null:f.isNaN(d)?i.test(d)?f.parseJSON(d):d:parseFloat(d)}catch(g){}f.data(a,c,d)}else d=b}return d}var c=a.document,d=a.navigator,e=a.location,f=function(){function J(){if(!e.isReady){try{c.documentElement.doScroll("left")}catch(a){setTimeout(J,1);return}e.ready()}}var e=function(a,b){return new e.fn.init(a,b,h)},f=a.jQuery,g=a.$,h,i=/^(?:[^<]*(<[\w\W]+>)[^>]*$|#([\w\-]*)$)/,j=/\S/,k=/^\s+/,l=/\s+$/,m=/\d/,n=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,o=/^[\],:{}\s]*$/,p=/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,q=/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,r=/(?:^|:|,)(?:\s*\[)+/g,s=/(webkit)[ \/]([\w.]+)/,t=/(opera)(?:.*version)?[ \/]([\w.]+)/,u=/(msie) ([\w.]+)/,v=/(mozilla)(?:.*? rv:([\w.]+))?/,w=/-([a-z])/ig,x=function(a,b){return b.toUpperCase()},y=d.userAgent,z,A,B,C=Object.prototype.toString,D=Object.prototype.hasOwnProperty,E=Array.prototype.push,F=Array.prototype.slice,G=String.prototype.trim,H=Array.prototype.indexOf,I={};e.fn=e.prototype={constructor:e,init:function(a,d,f){var g,h,j,k;if(!a)return this;if(a.nodeType){this.context=this[0]=a,this.length=1;return this}if(a==="body"&&!d&&c.body){this.context=c,this[0]=c.body,this.selector=a,this.length=1;return this}if(typeof a=="string"){a.charAt(0)!=="<"||a.charAt(a.length-1)!==">"||a.length<3?g=i.exec(a):g=[null,a,null];if(g&&(g[1]||!d)){if(g[1]){d=d instanceof e?d[0]:d,k=d?d.ownerDocument||d:c,j=n.exec(a),j?e.isPlainObject(d)?(a=[c.createElement(j[1])],e.fn.attr.call(a,d,!0)):a=[k.createElement(j[1])]:(j=e.buildFragment([g[1]],[k]),a=(j.cacheable?e.clone(j.fragment):j.fragment).childNodes);return e.merge(this,a)}h=c.getElementById(g[2]);if(h&&h.parentNode){if(h.id!==g[2])return f.find(a);this.length=1,this[0]=h}this.context=c,this.selector=a;return this}return!d||d.jquery?(d||f).find(a):this.constructor(d).find(a)}if(e.isFunction(a))return f.ready(a);a.selector!==b&&(this.selector=a.selector,this.context=a.context);return e.makeArray(a,this)},selector:"",jquery:"1.6.2",length:0,size:function(){return this.length},toArray:function(){return F.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this[this.length+a]:this[a]},pushStack:function(a,b,c){var d=this.constructor();e.isArray(a)?E.apply(d,a):e.merge(d,a),d.prevObject=this,d.context=this.context,b==="find"?d.selector=this.selector+(this.selector?" ":"")+c:b&&(d.selector=this.selector+"."+b+"("+c+")");return d},each:function(a,b){return e.each(this,a,b)},ready:function(a){e.bindReady(),A.done(a);return this},eq:function(a){return a===-1?this.slice(a):this.slice(a,+a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(F.apply(this,arguments),"slice",F.call(arguments).join(","))},map:function(a){return this.pushStack(e.map(this,function(b,c){return a.call(b,c,b)}))},end:function(){return this.prevObject||this.constructor(null)},push:E,sort:[].sort,splice:[].splice},e.fn.init.prototype=e.fn,e.extend=e.fn.extend=function(){var a,c,d,f,g,h,i=arguments[0]||{},j=1,k=arguments.length,l=!1;typeof i=="boolean"&&(l=i,i=arguments[1]||{},j=2),typeof i!="object"&&!e.isFunction(i)&&(i={}),k===j&&(i=this,--j);for(;j<k;j++)if((a=arguments[j])!=null)for(c in a){d=i[c],f=a[c];if(i===f)continue;l&&f&&(e.isPlainObject(f)||(g=e.isArray(f)))?(g?(g=!1,h=d&&e.isArray(d)?d:[]):h=d&&e.isPlainObject(d)?d:{},i[c]=e.extend(l,h,f)):f!==b&&(i[c]=f)}return i},e.extend({noConflict:function(b){a.$===e&&(a.$=g),b&&a.jQuery===e&&(a.jQuery=f);return e},isReady:!1,readyWait:1,holdReady:function(a){a?e.readyWait++:e.ready(!0)},ready:function(a){if(a===!0&&!--e.readyWait||a!==!0&&!e.isReady){if(!c.body)return setTimeout(e.ready,1);e.isReady=!0;if(a!==!0&&--e.readyWait>0)return;A.resolveWith(c,[e]),e.fn.trigger&&e(c).trigger("ready").unbind("ready")}},bindReady:function(){if(!A){A=e._Deferred();if(c.readyState==="complete")return setTimeout(e.ready,1);if(c.addEventListener)c.addEventListener("DOMContentLoaded",B,!1),a.addEventListener("load",e.ready,!1);else if(c.attachEvent){c.attachEvent("onreadystatechange",B),a.attachEvent("onload",e.ready);var b=!1;try{b=a.frameElement==null}catch(d){}c.documentElement.doScroll&&b&&J()}}},isFunction:function(a){return e.type(a)==="function"},isArray:Array.isArray||function(a){return e.type(a)==="array"},isWindow:function(a){return a&&typeof a=="object"&&"setInterval"in a},isNaN:function(a){return a==null||!m.test(a)||isNaN(a)},type:function(a){return a==null?String(a):I[C.call(a)]||"object"},isPlainObject:function(a){if(!a||e.type(a)!=="object"||a.nodeType||e.isWindow(a))return!1;if(a.constructor&&!D.call(a,"constructor")&&!D.call(a.constructor.prototype,"isPrototypeOf"))return!1;var c;for(c in a);return c===b||D.call(a,c)},isEmptyObject:function(a){for(var b in a)return!1;return!0},error:function(a){throw a},parseJSON:function(b){if(typeof b!="string"||!b)return null;b=e.trim(b);if(a.JSON&&a.JSON.parse)return a.JSON.parse(b);if(o.test(b.replace(p,"@").replace(q,"]").replace(r,"")))return(new Function("return "+b))();e.error("Invalid JSON: "+b)},parseXML:function(b,c,d){a.DOMParser?(d=new DOMParser,c=d.parseFromString(b,"text/xml")):(c=new ActiveXObject("Microsoft.XMLDOM"),c.async="false",c.loadXML(b)),d=c.documentElement,(!d||!d.nodeName||d.nodeName==="parsererror")&&e.error("Invalid XML: "+b);return c},noop:function(){},globalEval:function(b){b&&j.test(b)&&(a.execScript||function(b){a.eval.call(a,b)})(b)},camelCase:function(a){return a.replace(w,x)},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,c,d){var f,g=0,h=a.length,i=h===b||e.isFunction(a);if(d){if(i){for(f in a)if(c.apply(a[f],d)===!1)break}else for(;g<h;)if(c.apply(a[g++],d)===!1)break}else if(i){for(f in a)if(c.call(a[f],f,a[f])===!1)break}else for(;g<h;)if(c.call(a[g],g,a[g++])===!1)break;return a},trim:G?function(a){return a==null?"":G.call(a)}:function(a){return a==null?"":(a+"").replace(k,"").replace(l,"")},makeArray:function(a,b){var c=b||[];if(a!=null){var d=e.type(a);a.length==null||d==="string"||d==="function"||d==="regexp"||e.isWindow(a)?E.call(c,a):e.merge(c,a)}return c},inArray:function(a,b){if(H)return H.call(b,a);for(var c=0,d=b.length;c<d;c++)if(b[c]===a)return c;return-1},merge:function(a,c){var d=a.length,e=0;if(typeof c.length=="number")for(var f=c.length;e<f;e++)a[d++]=c[e];else while(c[e]!==b)a[d++]=c[e++];a.length=d;return a},grep:function(a,b,c){var d=[],e;c=!!c;for(var f=0,g=a.length;f<g;f++)e=!!b(a[f],f),c!==e&&d.push(a[f]);return d},map:function(a,c,d){var f,g,h=[],i=0,j=a.length,k=a instanceof e||j!==b&&typeof j=="number"&&(j>0&&a[0]&&a[j-1]||j===0||e.isArray(a));if(k)for(;i<j;i++)f=c(a[i],i,d),f!=null&&(h[h.length]=f);else for(g in a)f=c(a[g],g,d),f!=null&&(h[h.length]=f);return h.concat.apply([],h)},guid:1,proxy:function(a,c){if(typeof c=="string"){var d=a[c];c=a,a=d}if(!e.isFunction(a))return b;var f=F.call(arguments,2),g=function(){return a.apply(c,f.concat(F.call(arguments)))};g.guid=a.guid=a.guid||g.guid||e.guid++;return g},access:function(a,c,d,f,g,h){var i=a.length;if(typeof c=="object"){for(var j in c)e.access(a,j,c[j],f,g,d);return a}if(d!==b){f=!h&&f&&e.isFunction(d);for(var k=0;k<i;k++)g(a[k],c,f?d.call(a[k],k,g(a[k],c)):d,h);return a}return i?g(a[0],c):b},now:function(){return(new Date).getTime()},uaMatch:function(a){a=a.toLowerCase();var b=s.exec(a)||t.exec(a)||u.exec(a)||a.indexOf("compatible")<0&&v.exec(a)||[];return{browser:b[1]||"",version:b[2]||"0"}},sub:function(){function a(b,c){return new a.fn.init(b,c)}e.extend(!0,a,this),a.superclass=this,a.fn=a.prototype=this(),a.fn.constructor=a,a.sub=this.sub,a.fn.init=function(d,f){f&&f instanceof e&&!(f instanceof a)&&(f=a(f));return e.fn.init.call(this,d,f,b)},a.fn.init.prototype=a.fn;var b=a(c);return a},browser:{}}),e.each("Boolean Number String Function Array Date RegExp Object".split(" "),function(a,b){I["[object "+b+"]"]=b.toLowerCase()}),z=e.uaMatch(y),z.browser&&(e.browser[z.browser]=!0,e.browser.version=z.version),e.browser.webkit&&(e.browser.safari=!0),j.test(" ")&&(k=/^[\s\xA0]+/,l=/[\s\xA0]+$/),h=e(c),c.addEventListener?B=function(){c.removeEventListener("DOMContentLoaded",B,!1),e.ready()}:c.attachEvent&&(B=function(){c.readyState==="complete"&&(c.detachEvent("onreadystatechange",B),e.ready())});return e}(),g="done fail isResolved isRejected promise then always pipe".split(" "),h=[].slice;f.extend({_Deferred:function(){var a=[],b,c,d,e={done:function(){if(!d){var c=arguments,g,h,i,j,k;b&&(k=b,b=0);for(g=0,h=c.length;g<h;g++)i=c[g],j=f.type(i),j==="array"?e.done.apply(e,i):j==="function"&&a.push(i);k&&e.resolveWith(k[0],k[1])}return this},resolveWith:function(e,f){if(!d&&!b&&!c){f=f||[],c=1;try{while(a[0])a.shift().apply(e,f)}finally{b=[e,f],c=0}}return this},resolve:function(){e.resolveWith(this,arguments);return this},isResolved:function(){return!!c||!!b},cancel:function(){d=1,a=[];return this}};return e},Deferred:function(a){var b=f._Deferred(),c=f._Deferred(),d;f.extend(b,{then:function(a,c){b.done(a).fail(c);return this},always:function(){return b.done.apply(b,arguments).fail.apply(this,arguments)},fail:c.done,rejectWith:c.resolveWith,reject:c.resolve,isRejected:c.isResolved,pipe:function(a,c){return f.Deferred(function(d){f.each({done:[a,"resolve"],fail:[c,"reject"]},function(a,c){var e=c[0],g=c[1],h;f.isFunction(e)?b[a](function(){h=e.apply(this,arguments),h&&f.isFunction(h.promise)?h.promise().then(d.resolve,d.reject):d[g](h)}):b[a](d[g])})}).promise()},promise:function(a){if(a==null){if(d)return d;d=a={}}var c=g.length;while(c--)a[g[c]]=b[g[c]];return a}}),b.done(c.cancel).fail(b.cancel),delete b.cancel,a&&a.call(b,b);return b},when:function(a){function i(a){return function(c){b[a]=arguments.length>1?h.call(arguments,0):c,--e||g.resolveWith(g,h.call(b,0))}}var b=arguments,c=0,d=b.length,e=d,g=d<=1&&a&&f.isFunction(a.promise)?a:f.Deferred();if(d>1){for(;c<d;c++)b[c]&&f.isFunction(b[c].promise)?b[c].promise().then(i(c),g.reject):--e;e||g.resolveWith(g,b)}else g!==a&&g.resolveWith(g,d?[a]:[]);return g.promise()}}),f.support=function(){var a=c.createElement("div"),b=c.documentElement,d,e,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u;a.setAttribute("className","t"),a.innerHTML=" <link/><table></table><a href='/a' style='top:1px;float:left;opacity:.55;'>a</a><input type='checkbox'/>",d=a.getElementsByTagName("*"),e=a.getElementsByTagName("a")[0];if(!d||!d.length||!e)return{};g=c.createElement("select"),h=g.appendChild(c.createElement("option")),i=a.getElementsByTagName("input")[0],k={leadingWhitespace:a.firstChild.nodeType===3,tbody:!a.getElementsByTagName("tbody").length,htmlSerialize:!!a.getElementsByTagName("link").length,style:/top/.test(e.getAttribute("style")),hrefNormalized:e.getAttribute("href")==="/a",opacity:/^0.55$/.test(e.style.opacity),cssFloat:!!e.style.cssFloat,checkOn:i.value==="on",optSelected:h.selected,getSetAttribute:a.className!=="t",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0},i.checked=!0,k.noCloneChecked=i.cloneNode(!0).checked,g.disabled=!0,k.optDisabled=!h.disabled;try{delete a.test}catch(v){k.deleteExpando=!1}!a.addEventListener&&a.attachEvent&&a.fireEvent&&(a.attachEvent("onclick",function(){k.noCloneEvent=!1}),a.cloneNode(!0).fireEvent("onclick")),i=c.createElement("input"),i.value="t",i.setAttribute("type","radio"),k.radioValue=i.value==="t",i.setAttribute("checked","checked"),a.appendChild(i),l=c.createDocumentFragment(),l.appendChild(a.firstChild),k.checkClone=l.cloneNode(!0).cloneNode(!0).lastChild.checked,a.innerHTML="",a.style.width=a.style.paddingLeft="1px",m=c.getElementsByTagName("body")[0],o=c.createElement(m?"div":"body"),p={visibility:"hidden",width:0,height:0,border:0,margin:0},m&&f.extend(p,{position:"absolute",left:-1e3,top:-1e3});for(t in p)o.style[t]=p[t];o.appendChild(a),n=m||b,n.insertBefore(o,n.firstChild),k.appendChecked=i.checked,k.boxModel=a.offsetWidth===2,"zoom"in a.style&&(a.style.display="inline",a.style.zoom=1,k.inlineBlockNeedsLayout=a.offsetWidth===2,a.style.display="",a.innerHTML="<div style='width:4px;'></div>",k.shrinkWrapBlocks=a.offsetWidth!==2),a.innerHTML="<table><tr><td style='padding:0;border:0;display:none'></td><td>t</td></tr></table>",q=a.getElementsByTagName("td"),u=q[0].offsetHeight===0,q[0].style.display="",q[1].style.display="none",k.reliableHiddenOffsets=u&&q[0].offsetHeight===0,a.innerHTML="",c.defaultView&&c.defaultView.getComputedStyle&&(j=c.createElement("div"),j.style.width="0",j.style.marginRight="0",a.appendChild(j),k.reliableMarginRight=(parseInt((c.defaultView.getComputedStyle(j,null)||{marginRight:0}).marginRight,10)||0)===0),o.innerHTML="",n.removeChild(o);if(a.attachEvent)for(t in{submit:1,change:1,focusin:1})s="on"+t,u=s in a,u||(a.setAttribute(s,"return;"),u=typeof a[s]=="function"),k[t+"Bubbles"]=u;o=l=g=h=m=j=a=i=null;return k}(),f.boxModel=f.support.boxModel;var i=/^(?:\{.*\}|\[.*\])$/,j=/([a-z])([A-Z])/g;f.extend({cache:{},uuid:0,expando:"jQuery"+(f.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(a){a=a.nodeType?f.cache[a[f.expando]]:a[f.expando];return!!a&&!l(a)},data:function(a,c,d,e){if(!!f.acceptData(a)){var g=f.expando,h=typeof c=="string",i,j=a.nodeType,k=j?f.cache:a,l=j?a[f.expando]:a[f.expando]&&f.expando;if((!l||e&&l&&!k[l][g])&&h&&d===b)return;l||(j?a[f.expando]=l=++f.uuid:l=f.expando),k[l]||(k[l]={},j||(k[l].toJSON=f.noop));if(typeof c=="object"||typeof c=="function")e?k[l][g]=f.extend(k[l][g],c):k[l]=f.extend(k[l],c);i=k[l],e&&(i[g]||(i[g]={}),i=i[g]),d!==b&&(i[f.camelCase(c)]=d);if(c==="events"&&!i[c])return i[g]&&i[g].events;return h?i[f.camelCase(c)]||i[c]:i}},removeData:function(b,c,d){if(!!f.acceptData(b)){var e=f.expando,g=b.nodeType,h=g?f.cache:b,i=g?b[f.expando]:f.expando;if(!h[i])return;if(c){var j=d?h[i][e]:h[i];if(j){delete j[c];if(!l(j))return}}if(d){delete h[i][e];if(!l(h[i]))return}var k=h[i][e];f.support.deleteExpando||h!=a?delete h[i]:h[i]=null,k?(h[i]={},g||(h[i].toJSON=f.noop),h[i][e]=k):g&&(f.support.deleteExpando?delete b[f.expando]:b.removeAttribute?b.removeAttribute(f.expando):b[f.expando]=null)}},_data:function(a,b,c){return f.data(a,b,c,!0)},acceptData:function(a){if(a.nodeName){var b=f.noData[a.nodeName.toLowerCase()];if(b)return b!==!0&&a.getAttribute("classid")===b}return!0}}),f.fn.extend({data:function(a,c){var d=null;if(typeof a=="undefined"){if(this.length){d=f.data(this[0]);if(this[0].nodeType===1){var e=this[0].attributes,g;for(var h=0,i=e.length;h<i;h++)g=e[h].name,g.indexOf("data-")===0&&(g=f.camelCase(g.substring(5)),k(this[0],g,d[g]))}}return d}if(typeof a=="object")return this.each(function(){f.data(this,a)});var j=a.split(".");j[1]=j[1]?"."+j[1]:"";if(c===b){d=this.triggerHandler("getData"+j[1]+"!",[j[0]]),d===b&&this.length&&(d=f.data(this[0],a),d=k(this[0],a,d));return d===b&&j[1]?this.data(j[0]):d}return this.each(function(){var b=f(this),d=[j[0],c];b.triggerHandler("setData"+j[1]+"!",d),f.data(this,a,c),b.triggerHandler("changeData"+j[1]+"!",d)})},removeData:function(a){return this.each(function(){f.removeData(this,a)})}}),f.extend({_mark:function(a,c){a&&(c=(c||"fx")+"mark",f.data(a,c,(f.data(a,c,b,!0)||0)+1,!0))},_unmark:function(a,c,d){a!==!0&&(d=c,c=a,a=!1);if(c){d=d||"fx";var e=d+"mark",g=a?0:(f.data(c,e,b,!0)||1)-1;g?f.data(c,e,g,!0):(f.removeData(c,e,!0),m(c,d,"mark"))}},queue:function(a,c,d){if(a){c=(c||"fx")+"queue";var e=f.data(a,c,b,!0);d&&(!e||f.isArray(d)?e=f.data(a,c,f.makeArray(d),!0):e.push(d));return e||[]}},dequeue:function(a,b){b=b||"fx";var c=f.queue(a,b),d=c.shift(),e;d==="inprogress"&&(d=c.shift()),d&&(b==="fx"&&c.unshift("inprogress"),d.call(a,function(){f.dequeue(a,b)})),c.length||(f.removeData(a,b+"queue",!0),m(a,b,"queue"))}}),f.fn.extend({queue:function(a,c){typeof a!="string"&&(c=a,a="fx");if(c===b)return f.queue(this[0],a);return this.each(function(){var b=f.queue(this,a,c);a==="fx"&&b[0]!=="inprogress"&&f.dequeue(this,a)})},dequeue:function(a){return this.each(function(){f.dequeue(this,a)})},delay:function(a,b){a=f.fx?f.fx.speeds[a]||a:a,b=b||"fx";return this.queue(b,function(){var c=this;setTimeout(function(){f.dequeue(c,b)},a)})},clearQueue:function(a){return this.queue(a||"fx",[])},promise:function(a,c){function m(){--h||d.resolveWith(e,[e])}typeof a!="string"&&(c=a,a=b),a=a||"fx";var d=f.Deferred(),e=this,g=e.length,h=1,i=a+"defer",j=a+"queue",k=a+"mark",l;while(g--)if(l=f.data(e[g],i,b,!0)||(f.data(e[g],j,b,!0)||f.data(e[g],k,b,!0))&&f.data(e[g],i,f._Deferred(),!0))h++,l.done(m);m();return d.promise()}});var n=/[\n\t\r]/g,o=/\s+/,p=/\r/g,q=/^(?:button|input)$/i,r=/^(?:button|input|object|select|textarea)$/i,s=/^a(?:rea)?$/i,t=/^(?:autofocus|autoplay|async|checked|controls|defer|disabled|hidden|loop|multiple|open|readonly|required|scoped|selected)$/i,u=/\:|^on/,v,w;f.fn.extend({attr:function(a,b){return f.access(this,a,b,!0,f.attr)},removeAttr:function(a){return this.each(function(){f.removeAttr(this,a)})},prop:function(a,b){return f.access(this,a,b,!0,f.prop)},removeProp:function(a){a=f.propFix[a]||a;return this.each(function(){try{this[a]=b,delete this[a]}catch(c){}})},addClass:function(a){var b,c,d,e,g,h,i;if(f.isFunction(a))return this.each(function(b){f(this).addClass(a.call(this,b,this.className))});if(a&&typeof a=="string"){b=a.split(o);for(c=0,d=this.length;c<d;c++){e=this[c];if(e.nodeType===1)if(!e.className&&b.length===1)e.className=a;else{g=" "+e.className+" ";for(h=0,i=b.length;h<i;h++)~g.indexOf(" "+b[h]+" ")||(g+=b[h]+" ");e.className=f.trim(g)}}}return this},removeClass:function(a){var c,d,e,g,h,i,j;if(f.isFunction(a))return this.each(function(b){f(this).removeClass(a.call(this,b,this.className))});if(a&&typeof a=="string"||a===b){c=(a||"").split(o);for(d=0,e=this.length;d<e;d++){g=this[d];if(g.nodeType===1&&g.className)if(a){h=(" "+g.className+" ").replace(n," ");for(i=0,j=c.length;i<j;i++)h=h.replace(" "+c[i]+" "," ");g.className=f.trim(h)}else g.className=""}}return this},toggleClass:function(a,b){var c=typeof a,d=typeof b=="boolean";if(f.isFunction(a))return this.each(function(c){f(this).toggleClass(a.call(this,c,this.className,b),b)});return this.each(function(){if(c==="string"){var e,g=0,h=f(this),i=b,j=a.split(o);while(e=j[g++])i=d?i:!h.hasClass(e),h[i?"addClass":"removeClass"](e)}else if(c==="undefined"||c==="boolean")this.className&&f._data(this,"__className__",this.className),this.className=this.className||a===!1?"":f._data(this,"__className__")||""})},hasClass:function(a){var b=" "+a+" ";for(var c=0,d=this.length;c<d;c++)if((" "+this[c].className+" ").replace(n," ").indexOf(b)>-1)return!0;return!1},val:function(a){var c,d,e=this[0];if(!arguments.length){if(e){c=f.valHooks[e.nodeName.toLowerCase()]||f.valHooks[e.type];if(c&&"get"in c&&(d=c.get(e,"value"))!==b)return d;d=e.value;return typeof d=="string"?d.replace(p,""):d==null?"":d}return b}var g=f.isFunction(a);return this.each(function(d){var e=f(this),h;if(this.nodeType===1){g?h=a.call(this,d,e.val()):h=a,h==null?h="":typeof h=="number"?h+="":f.isArray(h)&&(h=f.map(h,function(a){return a==null?"":a+""})),c=f.valHooks[this.nodeName.toLowerCase()]||f.valHooks[this.type];if(!c||!("set"in c)||c.set(this,h,"value")===b)this.value=h}})}}),f.extend({valHooks:{option:{get:function(a){var b=a.attributes.value;return!b||b.specified?a.value:a.text}},select:{get:function(a){var b,c=a.selectedIndex,d=[],e=a.options,g=a.type==="select-one";if(c<0)return null;for(var h=g?c:0,i=g?c+1:e.length;h<i;h++){var j=e[h];if(j.selected&&(f.support.optDisabled?!j.disabled:j.getAttribute("disabled")===null)&&(!j.parentNode.disabled||!f.nodeName(j.parentNode,"optgroup"))){b=f(j).val();if(g)return b;d.push(b)}}if(g&&!d.length&&e.length)return f(e[c]).val();return d},set:function(a,b){var c=f.makeArray(b);f(a).find("option").each(function(){this.selected=f.inArray(f(this).val(),c)>=0}),c.length||(a.selectedIndex=-1);return c}}},attrFn:{val:!0,css:!0,html:!0,text:!0,data:!0,width:!0,height:!0,offset:!0},attrFix:{tabindex:"tabIndex"},attr:function(a,c,d,e){var g=a.nodeType;if(!a||g===3||g===8||g===2)return b;if(e&&c in f.attrFn)return f(a)[c](d);if(!("getAttribute"in a))return f.prop(a,c,d);var h,i,j=g!==1||!f.isXMLDoc(a);j&&(c=f.attrFix[c]||c,i=f.attrHooks[c],i||(t.test(c)?i=w:v&&c!=="className"&&(f.nodeName(a,"form")||u.test(c))&&(i=v)));if(d!==b){if(d===null){f.removeAttr(a,c);return b}if(i&&"set"in i&&j&&(h=i.set(a,d,c))!==b)return h;a.setAttribute(c,""+d);return d}if(i&&"get"in i&&j&&(h=i.get(a,c))!==null)return h;h=a.getAttribute(c);return h===null?b:h},removeAttr:function(a,b){var c;a.nodeType===1&&(b=f.attrFix[b]||b,f.support.getSetAttribute?a.removeAttribute(b):(f.attr(a,b,""),a.removeAttributeNode(a.getAttributeNode(b))),t.test(b)&&(c=f.propFix[b]||b)in a&&(a[c]=!1))},attrHooks:{type:{set:function(a,b){if(q.test(a.nodeName)&&a.parentNode)f.error("type property can't be changed");else if(!f.support.radioValue&&b==="radio"&&f.nodeName(a,"input")){var c=a.value;a.setAttribute("type",b),c&&(a.value=c);return b}}},tabIndex:{get:function(a){var c=a.getAttributeNode("tabIndex");return c&&c.specified?parseInt(c.value,10):r.test(a.nodeName)||s.test(a.nodeName)&&a.href?0:b}},value:{get:function(a,b){if(v&&f.nodeName(a,"button"))return v.get(a,b);return b in a?a.value:null},set:function(a,b,c){if(v&&f.nodeName(a,"button"))return v.set(a,b,c);a.value=b}}},propFix:{tabindex:"tabIndex",readonly:"readOnly","for":"htmlFor","class":"className",maxlength:"maxLength",cellspacing:"cellSpacing",cellpadding:"cellPadding",rowspan:"rowSpan",colspan:"colSpan",usemap:"useMap",frameborder:"frameBorder",contenteditable:"contentEditable"},prop:function(a,c,d){var e=a.nodeType;if(!a||e===3||e===8||e===2)return b;var g,h,i=e!==1||!f.isXMLDoc(a);i&&(c=f.propFix[c]||c,h=f.propHooks[c]);return d!==b?h&&"set"in h&&(g=h.set(a,d,c))!==b?g:a[c]=d:h&&"get"in h&&(g=h.get(a,c))!==b?g:a[c]},propHooks:{}}),w={get:function(a,c){return f.prop(a,c)?c.toLowerCase():b},set:function(a,b,c){var d;b===!1?f.removeAttr(a,c):(d=f.propFix[c]||c,d in a&&(a[d]=!0),a.setAttribute(c,c.toLowerCase()));return c}},f.support.getSetAttribute||(f.attrFix=f.propFix,v=f.attrHooks.name=f.attrHooks.title=f.valHooks.button={get:function(a,c){var d;d=a.getAttributeNode(c);return d&&d.nodeValue!==""?d.nodeValue:b},set:function(a,b,c){var d=a.getAttributeNode(c);if(d){d.nodeValue=b;return b}}},f.each(["width","height"],function(a,b){f.attrHooks[b]=f.extend(f.attrHooks[b],{set:function(a,c){if(c===""){a.setAttribute(b,"auto");return c}}})})),f.support.hrefNormalized||f.each(["href","src","width","height"],function(a,c){f.attrHooks[c]=f.extend(f.attrHooks[c],{get:function(a){var d=a.getAttribute(c,2);return d===null?b:d}})}),f.support.style||(f.attrHooks.style={get:function(a){return a.style.cssText.toLowerCase()||b},set:function(a,b){return a.style.cssText=""+b}}),f.support.optSelected||(f.propHooks.selected=f.extend(f.propHooks.selected,{get:function(a){var b=a.parentNode;b&&(b.selectedIndex,b.parentNode&&b.parentNode.selectedIndex)}})),f.support.checkOn||f.each(["radio","checkbox"],function(){f.valHooks[this]={get:function(a){return a.getAttribute("value")===null?"on":a.value}}}),f.each(["radio","checkbox"],function(){f.valHooks[this]=f.extend(f.valHooks[this],{set:function(a,b){if(f.isArray(b))return a.checked=f.inArray(f(a).val(),b)>=0}})});var x=/\.(.*)$/,y=/^(?:textarea|input|select)$/i,z=/\./g,A=/ /g,B=/[^\w\s.|`]/g,C=function(a){return a.replace(B,"\\$&")};f.event={add:function(a,c,d,e){if(a.nodeType!==3&&a.nodeType!==8){if(d===!1)d=D;else if(!d)return;var g,h;d.handler&&(g=d,d=g.handler),d.guid||(d.guid=f.guid++);var i=f._data(a);if(!i)return;var j=i.events,k=i.handle;j||(i.events=j={}),k||(i.handle=k=function(a){return typeof f!="undefined"&&(!a||f.event.triggered!==a.type)?f.event.handle.apply(k.elem,arguments):b}),k.elem=a,c=c.split(" ");var l,m=0,n;while(l=c[m++]){h=g?f.extend({},g):{handler:d,data:e},l.indexOf(".")>-1?(n=l.split("."),l=n.shift(),h.namespace=n.slice(0).sort().join(".")):(n=[],h.namespace=""),h.type=l,h.guid||(h.guid=d.guid);var o=j[l],p=f.event.special[l]||{};if(!o){o=j[l]=[];if(!p.setup||p.setup.call(a,e,n,k)===!1)a.addEventListener?a.addEventListener(l,k,!1):a.attachEvent&&a.attachEvent("on"+l,k)}p.add&&(p.add.call(a,h),h.handler.guid||(h.handler.guid=d.guid)),o.push(h),f.event.global[l]=!0}a=null}},global:{},remove:function(a,c,d,e){if(a.nodeType!==3&&a.nodeType!==8){d===!1&&(d=D);var g,h,i,j,k=0,l,m,n,o,p,q,r,s=f.hasData(a)&&f._data(a),t=s&&s.events;if(!s||!t)return;c&&c.type&&(d=c.handler,c=c.type);if(!c||typeof c=="string"&&c.charAt(0)==="."){c=c||"";for(h in t)f.event.remove(a,h+c);return}c=c.split(" ");while(h=c[k++]){r=h,q=null,l=h.indexOf(".")<0,m=[],l||(m=h.split("."),h=m.shift(),n=new RegExp("(^|\\.)"+f.map(m.slice(0).sort(),C).join("\\.(?:.*\\.)?")+"(\\.|$)")),p=t[h];if(!p)continue;if(!d){for(j=0;j<p.length;j++){q=p[j];if(l||n.test(q.namespace))f.event.remove(a,r,q.handler,j),p.splice(j--,1)}continue}o=f.event.special[h]||{};for(j=e||0;j<p.length;j++){q=p[j];if(d.guid===q.guid){if(l||n.test(q.namespace))e==null&&p.splice(j--,1),o.remove&&o.remove.call(a,q);if(e!=null)break}}if(p.length===0||e!=null&&p.length===1)(!o.teardown||o.teardown.call(a,m)===!1)&&f.removeEvent(a,h,s.handle),g=null,delete t[h]}if(f.isEmptyObject(t)){var u=s.handle;u&&(u.elem=null),delete s.events,delete s.handle,f.isEmptyObject(s)&&f.removeData(a,b,!0)}}},customEvent:{getData:!0,setData:!0,changeData:!0},trigger:function(c,d,e,g){var h=c.type||c,i=[],j;h.indexOf("!")>=0&&(h=h.slice(0,-1),j=!0),h.indexOf(".")>=0&&(i=h.split("."),h=i. -shift(),i.sort());if(!!e&&!f.event.customEvent[h]||!!f.event.global[h]){c=typeof c=="object"?c[f.expando]?c:new f.Event(h,c):new f.Event(h),c.type=h,c.exclusive=j,c.namespace=i.join("."),c.namespace_re=new RegExp("(^|\\.)"+i.join("\\.(?:.*\\.)?")+"(\\.|$)");if(g||!e)c.preventDefault(),c.stopPropagation();if(!e){f.each(f.cache,function(){var a=f.expando,b=this[a];b&&b.events&&b.events[h]&&f.event.trigger(c,d,b.handle.elem)});return}if(e.nodeType===3||e.nodeType===8)return;c.result=b,c.target=e,d=d!=null?f.makeArray(d):[],d.unshift(c);var k=e,l=h.indexOf(":")<0?"on"+h:"";do{var m=f._data(k,"handle");c.currentTarget=k,m&&m.apply(k,d),l&&f.acceptData(k)&&k[l]&&k[l].apply(k,d)===!1&&(c.result=!1,c.preventDefault()),k=k.parentNode||k.ownerDocument||k===c.target.ownerDocument&&a}while(k&&!c.isPropagationStopped());if(!c.isDefaultPrevented()){var n,o=f.event.special[h]||{};if((!o._default||o._default.call(e.ownerDocument,c)===!1)&&(h!=="click"||!f.nodeName(e,"a"))&&f.acceptData(e)){try{l&&e[h]&&(n=e[l],n&&(e[l]=null),f.event.triggered=h,e[h]())}catch(p){}n&&(e[l]=n),f.event.triggered=b}}return c.result}},handle:function(c){c=f.event.fix(c||a.event);var d=((f._data(this,"events")||{})[c.type]||[]).slice(0),e=!c.exclusive&&!c.namespace,g=Array.prototype.slice.call(arguments,0);g[0]=c,c.currentTarget=this;for(var h=0,i=d.length;h<i;h++){var j=d[h];if(e||c.namespace_re.test(j.namespace)){c.handler=j.handler,c.data=j.data,c.handleObj=j;var k=j.handler.apply(this,g);k!==b&&(c.result=k,k===!1&&(c.preventDefault(),c.stopPropagation()));if(c.isImmediatePropagationStopped())break}}return c.result},props:"altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode layerX layerY metaKey newValue offsetX offsetY pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target toElement view wheelDelta which".split(" "),fix:function(a){if(a[f.expando])return a;var d=a;a=f.Event(d);for(var e=this.props.length,g;e;)g=this.props[--e],a[g]=d[g];a.target||(a.target=a.srcElement||c),a.target.nodeType===3&&(a.target=a.target.parentNode),!a.relatedTarget&&a.fromElement&&(a.relatedTarget=a.fromElement===a.target?a.toElement:a.fromElement);if(a.pageX==null&&a.clientX!=null){var h=a.target.ownerDocument||c,i=h.documentElement,j=h.body;a.pageX=a.clientX+(i&&i.scrollLeft||j&&j.scrollLeft||0)-(i&&i.clientLeft||j&&j.clientLeft||0),a.pageY=a.clientY+(i&&i.scrollTop||j&&j.scrollTop||0)-(i&&i.clientTop||j&&j.clientTop||0)}a.which==null&&(a.charCode!=null||a.keyCode!=null)&&(a.which=a.charCode!=null?a.charCode:a.keyCode),!a.metaKey&&a.ctrlKey&&(a.metaKey=a.ctrlKey),!a.which&&a.button!==b&&(a.which=a.button&1?1:a.button&2?3:a.button&4?2:0);return a},guid:1e8,proxy:f.proxy,special:{ready:{setup:f.bindReady,teardown:f.noop},live:{add:function(a){f.event.add(this,N(a.origType,a.selector),f.extend({},a,{handler:M,guid:a.handler.guid}))},remove:function(a){f.event.remove(this,N(a.origType,a.selector),a)}},beforeunload:{setup:function(a,b,c){f.isWindow(this)&&(this.onbeforeunload=c)},teardown:function(a,b){this.onbeforeunload===b&&(this.onbeforeunload=null)}}}},f.removeEvent=c.removeEventListener?function(a,b,c){a.removeEventListener&&a.removeEventListener(b,c,!1)}:function(a,b,c){a.detachEvent&&a.detachEvent("on"+b,c)},f.Event=function(a,b){if(!this.preventDefault)return new f.Event(a,b);a&&a.type?(this.originalEvent=a,this.type=a.type,this.isDefaultPrevented=a.defaultPrevented||a.returnValue===!1||a.getPreventDefault&&a.getPreventDefault()?E:D):this.type=a,b&&f.extend(this,b),this.timeStamp=f.now(),this[f.expando]=!0},f.Event.prototype={preventDefault:function(){this.isDefaultPrevented=E;var a=this.originalEvent;!a||(a.preventDefault?a.preventDefault():a.returnValue=!1)},stopPropagation:function(){this.isPropagationStopped=E;var a=this.originalEvent;!a||(a.stopPropagation&&a.stopPropagation(),a.cancelBubble=!0)},stopImmediatePropagation:function(){this.isImmediatePropagationStopped=E,this.stopPropagation()},isDefaultPrevented:D,isPropagationStopped:D,isImmediatePropagationStopped:D};var F=function(a){var b=a.relatedTarget,c=!1,d=a.type;a.type=a.data,b!==this&&(b&&(c=f.contains(this,b)),c||(f.event.handle.apply(this,arguments),a.type=d))},G=function(a){a.type=a.data,f.event.handle.apply(this,arguments)};f.each({mouseenter:"mouseover",mouseleave:"mouseout"},function(a,b){f.event.special[a]={setup:function(c){f.event.add(this,b,c&&c.selector?G:F,a)},teardown:function(a){f.event.remove(this,b,a&&a.selector?G:F)}}}),f.support.submitBubbles||(f.event.special.submit={setup:function(a,b){if(!f.nodeName(this,"form"))f.event.add(this,"click.specialSubmit",function(a){var b=a.target,c=b.type;(c==="submit"||c==="image")&&f(b).closest("form").length&&K("submit",this,arguments)}),f.event.add(this,"keypress.specialSubmit",function(a){var b=a.target,c=b.type;(c==="text"||c==="password")&&f(b).closest("form").length&&a.keyCode===13&&K("submit",this,arguments)});else return!1},teardown:function(a){f.event.remove(this,".specialSubmit")}});if(!f.support.changeBubbles){var H,I=function(a){var b=a.type,c=a.value;b==="radio"||b==="checkbox"?c=a.checked:b==="select-multiple"?c=a.selectedIndex>-1?f.map(a.options,function(a){return a.selected}).join("-"):"":f.nodeName(a,"select")&&(c=a.selectedIndex);return c},J=function(c){var d=c.target,e,g;if(!!y.test(d.nodeName)&&!d.readOnly){e=f._data(d,"_change_data"),g=I(d),(c.type!=="focusout"||d.type!=="radio")&&f._data(d,"_change_data",g);if(e===b||g===e)return;if(e!=null||g)c.type="change",c.liveFired=b,f.event.trigger(c,arguments[1],d)}};f.event.special.change={filters:{focusout:J,beforedeactivate:J,click:function(a){var b=a.target,c=f.nodeName(b,"input")?b.type:"";(c==="radio"||c==="checkbox"||f.nodeName(b,"select"))&&J.call(this,a)},keydown:function(a){var b=a.target,c=f.nodeName(b,"input")?b.type:"";(a.keyCode===13&&!f.nodeName(b,"textarea")||a.keyCode===32&&(c==="checkbox"||c==="radio")||c==="select-multiple")&&J.call(this,a)},beforeactivate:function(a){var b=a.target;f._data(b,"_change_data",I(b))}},setup:function(a,b){if(this.type==="file")return!1;for(var c in H)f.event.add(this,c+".specialChange",H[c]);return y.test(this.nodeName)},teardown:function(a){f.event.remove(this,".specialChange");return y.test(this.nodeName)}},H=f.event.special.change.filters,H.focus=H.beforeactivate}f.support.focusinBubbles||f.each({focus:"focusin",blur:"focusout"},function(a,b){function e(a){var c=f.event.fix(a);c.type=b,c.originalEvent={},f.event.trigger(c,null,c.target),c.isDefaultPrevented()&&a.preventDefault()}var d=0;f.event.special[b]={setup:function(){d++===0&&c.addEventListener(a,e,!0)},teardown:function(){--d===0&&c.removeEventListener(a,e,!0)}}}),f.each(["bind","one"],function(a,c){f.fn[c]=function(a,d,e){var g;if(typeof a=="object"){for(var h in a)this[c](h,d,a[h],e);return this}if(arguments.length===2||d===!1)e=d,d=b;c==="one"?(g=function(a){f(this).unbind(a,g);return e.apply(this,arguments)},g.guid=e.guid||f.guid++):g=e;if(a==="unload"&&c!=="one")this.one(a,d,e);else for(var i=0,j=this.length;i<j;i++)f.event.add(this[i],a,g,d);return this}}),f.fn.extend({unbind:function(a,b){if(typeof a=="object"&&!a.preventDefault)for(var c in a)this.unbind(c,a[c]);else for(var d=0,e=this.length;d<e;d++)f.event.remove(this[d],a,b);return this},delegate:function(a,b,c,d){return this.live(b,c,d,a)},undelegate:function(a,b,c){return arguments.length===0?this.unbind("live"):this.die(b,null,c,a)},trigger:function(a,b){return this.each(function(){f.event.trigger(a,b,this)})},triggerHandler:function(a,b){if(this[0])return f.event.trigger(a,b,this[0],!0)},toggle:function(a){var b=arguments,c=a.guid||f.guid++,d=0,e=function(c){var e=(f.data(this,"lastToggle"+a.guid)||0)%d;f.data(this,"lastToggle"+a.guid,e+1),c.preventDefault();return b[e].apply(this,arguments)||!1};e.guid=c;while(d<b.length)b[d++].guid=c;return this.click(e)},hover:function(a,b){return this.mouseenter(a).mouseleave(b||a)}});var L={focus:"focusin",blur:"focusout",mouseenter:"mouseover",mouseleave:"mouseout"};f.each(["live","die"],function(a,c){f.fn[c]=function(a,d,e,g){var h,i=0,j,k,l,m=g||this.selector,n=g?this:f(this.context);if(typeof a=="object"&&!a.preventDefault){for(var o in a)n[c](o,d,a[o],m);return this}if(c==="die"&&!a&&g&&g.charAt(0)==="."){n.unbind(g);return this}if(d===!1||f.isFunction(d))e=d||D,d=b;a=(a||"").split(" ");while((h=a[i++])!=null){j=x.exec(h),k="",j&&(k=j[0],h=h.replace(x,""));if(h==="hover"){a.push("mouseenter"+k,"mouseleave"+k);continue}l=h,L[h]?(a.push(L[h]+k),h=h+k):h=(L[h]||h)+k;if(c==="live")for(var p=0,q=n.length;p<q;p++)f.event.add(n[p],"live."+N(h,m),{data:d,selector:m,handler:e,origType:h,origHandler:e,preType:l});else n.unbind("live."+N(h,m),e)}return this}}),f.each("blur focus focusin focusout load resize scroll unload click dblclick mousedown mouseup mousemove mouseover mouseout mouseenter mouseleave change select submit keydown keypress keyup error".split(" "),function(a,b){f.fn[b]=function(a,c){c==null&&(c=a,a=null);return arguments.length>0?this.bind(b,a,c):this.trigger(b)},f.attrFn&&(f.attrFn[b]=!0)}),function(){function u(a,b,c,d,e,f){for(var g=0,h=d.length;g<h;g++){var i=d[g];if(i){var j=!1;i=i[a];while(i){if(i.sizcache===c){j=d[i.sizset];break}if(i.nodeType===1){f||(i.sizcache=c,i.sizset=g);if(typeof b!="string"){if(i===b){j=!0;break}}else if(k.filter(b,[i]).length>0){j=i;break}}i=i[a]}d[g]=j}}}function t(a,b,c,d,e,f){for(var g=0,h=d.length;g<h;g++){var i=d[g];if(i){var j=!1;i=i[a];while(i){if(i.sizcache===c){j=d[i.sizset];break}i.nodeType===1&&!f&&(i.sizcache=c,i.sizset=g);if(i.nodeName.toLowerCase()===b){j=i;break}i=i[a]}d[g]=j}}}var a=/((?:\((?:\([^()]+\)|[^()]+)+\)|\[(?:\[[^\[\]]*\]|['"][^'"]*['"]|[^\[\]'"]+)+\]|\\.|[^ >+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,d=0,e=Object.prototype.toString,g=!1,h=!0,i=/\\/g,j=/\W/;[0,0].sort(function(){h=!1;return 0});var k=function(b,d,f,g){f=f||[],d=d||c;var h=d;if(d.nodeType!==1&&d.nodeType!==9)return[];if(!b||typeof b!="string")return f;var i,j,n,o,q,r,s,t,u=!0,w=k.isXML(d),x=[],y=b;do{a.exec(""),i=a.exec(y);if(i){y=i[3],x.push(i[1]);if(i[2]){o=i[3];break}}}while(i);if(x.length>1&&m.exec(b))if(x.length===2&&l.relative[x[0]])j=v(x[0]+x[1],d);else{j=l.relative[x[0]]?[d]:k(x.shift(),d);while(x.length)b=x.shift(),l.relative[b]&&(b+=x.shift()),j=v(b,j)}else{!g&&x.length>1&&d.nodeType===9&&!w&&l.match.ID.test(x[0])&&!l.match.ID.test(x[x.length-1])&&(q=k.find(x.shift(),d,w),d=q.expr?k.filter(q.expr,q.set)[0]:q.set[0]);if(d){q=g?{expr:x.pop(),set:p(g)}:k.find(x.pop(),x.length===1&&(x[0]==="~"||x[0]==="+")&&d.parentNode?d.parentNode:d,w),j=q.expr?k.filter(q.expr,q.set):q.set,x.length>0?n=p(j):u=!1;while(x.length)r=x.pop(),s=r,l.relative[r]?s=x.pop():r="",s==null&&(s=d),l.relative[r](n,s,w)}else n=x=[]}n||(n=j),n||k.error(r||b);if(e.call(n)==="[object Array]")if(!u)f.push.apply(f,n);else if(d&&d.nodeType===1)for(t=0;n[t]!=null;t++)n[t]&&(n[t]===!0||n[t].nodeType===1&&k.contains(d,n[t]))&&f.push(j[t]);else for(t=0;n[t]!=null;t++)n[t]&&n[t].nodeType===1&&f.push(j[t]);else p(n,f);o&&(k(o,h,f,g),k.uniqueSort(f));return f};k.uniqueSort=function(a){if(r){g=h,a.sort(r);if(g)for(var b=1;b<a.length;b++)a[b]===a[b-1]&&a.splice(b--,1)}return a},k.matches=function(a,b){return k(a,null,null,b)},k.matchesSelector=function(a,b){return k(b,null,null,[a]).length>0},k.find=function(a,b,c){var d;if(!a)return[];for(var e=0,f=l.order.length;e<f;e++){var g,h=l.order[e];if(g=l.leftMatch[h].exec(a)){var j=g[1];g.splice(1,1);if(j.substr(j.length-1)!=="\\"){g[1]=(g[1]||"").replace(i,""),d=l.find[h](g,b,c);if(d!=null){a=a.replace(l.match[h],"");break}}}}d||(d=typeof b.getElementsByTagName!="undefined"?b.getElementsByTagName("*"):[]);return{set:d,expr:a}},k.filter=function(a,c,d,e){var f,g,h=a,i=[],j=c,m=c&&c[0]&&k.isXML(c[0]);while(a&&c.length){for(var n in l.filter)if((f=l.leftMatch[n].exec(a))!=null&&f[2]){var o,p,q=l.filter[n],r=f[1];g=!1,f.splice(1,1);if(r.substr(r.length-1)==="\\")continue;j===i&&(i=[]);if(l.preFilter[n]){f=l.preFilter[n](f,j,d,i,e,m);if(!f)g=o=!0;else if(f===!0)continue}if(f)for(var s=0;(p=j[s])!=null;s++)if(p){o=q(p,f,s,j);var t=e^!!o;d&&o!=null?t?g=!0:j[s]=!1:t&&(i.push(p),g=!0)}if(o!==b){d||(j=i),a=a.replace(l.match[n],"");if(!g)return[];break}}if(a===h)if(g==null)k.error(a);else break;h=a}return j},k.error=function(a){throw"Syntax error, unrecognized expression: "+a};var l=k.selectors={order:["ID","NAME","TAG"],match:{ID:/#((?:[\w\u00c0-\uFFFF\-]|\\.)+)/,CLASS:/\.((?:[\w\u00c0-\uFFFF\-]|\\.)+)/,NAME:/\[name=['"]*((?:[\w\u00c0-\uFFFF\-]|\\.)+)['"]*\]/,ATTR:/\[\s*((?:[\w\u00c0-\uFFFF\-]|\\.)+)\s*(?:(\S?=)\s*(?:(['"])(.*?)\3|(#?(?:[\w\u00c0-\uFFFF\-]|\\.)*)|)|)\s*\]/,TAG:/^((?:[\w\u00c0-\uFFFF\*\-]|\\.)+)/,CHILD:/:(only|nth|last|first)-child(?:\(\s*(even|odd|(?:[+\-]?\d+|(?:[+\-]?\d*)?n\s*(?:[+\-]\s*\d+)?))\s*\))?/,POS:/:(nth|eq|gt|lt|first|last|even|odd)(?:\((\d*)\))?(?=[^\-]|$)/,PSEUDO:/:((?:[\w\u00c0-\uFFFF\-]|\\.)+)(?:\((['"]?)((?:\([^\)]+\)|[^\(\)]*)+)\2\))?/},leftMatch:{},attrMap:{"class":"className","for":"htmlFor"},attrHandle:{href:function(a){return a.getAttribute("href")},type:function(a){return a.getAttribute("type")}},relative:{"+":function(a,b){var c=typeof b=="string",d=c&&!j.test(b),e=c&&!d;d&&(b=b.toLowerCase());for(var f=0,g=a.length,h;f<g;f++)if(h=a[f]){while((h=h.previousSibling)&&h.nodeType!==1);a[f]=e||h&&h.nodeName.toLowerCase()===b?h||!1:h===b}e&&k.filter(b,a,!0)},">":function(a,b){var c,d=typeof b=="string",e=0,f=a.length;if(d&&!j.test(b)){b=b.toLowerCase();for(;e<f;e++){c=a[e];if(c){var g=c.parentNode;a[e]=g.nodeName.toLowerCase()===b?g:!1}}}else{for(;e<f;e++)c=a[e],c&&(a[e]=d?c.parentNode:c.parentNode===b);d&&k.filter(b,a,!0)}},"":function(a,b,c){var e,f=d++,g=u;typeof b=="string"&&!j.test(b)&&(b=b.toLowerCase(),e=b,g=t),g("parentNode",b,f,a,e,c)},"~":function(a,b,c){var e,f=d++,g=u;typeof b=="string"&&!j.test(b)&&(b=b.toLowerCase(),e=b,g=t),g("previousSibling",b,f,a,e,c)}},find:{ID:function(a,b,c){if(typeof b.getElementById!="undefined"&&!c){var d=b.getElementById(a[1]);return d&&d.parentNode?[d]:[]}},NAME:function(a,b){if(typeof b.getElementsByName!="undefined"){var c=[],d=b.getElementsByName(a[1]);for(var e=0,f=d.length;e<f;e++)d[e].getAttribute("name")===a[1]&&c.push(d[e]);return c.length===0?null:c}},TAG:function(a,b){if(typeof b.getElementsByTagName!="undefined")return b.getElementsByTagName(a[1])}},preFilter:{CLASS:function(a,b,c,d,e,f){a=" "+a[1].replace(i,"")+" ";if(f)return a;for(var g=0,h;(h=b[g])!=null;g++)h&&(e^(h.className&&(" "+h.className+" ").replace(/[\t\n\r]/g," ").indexOf(a)>=0)?c||d.push(h):c&&(b[g]=!1));return!1},ID:function(a){return a[1].replace(i,"")},TAG:function(a,b){return a[1].replace(i,"").toLowerCase()},CHILD:function(a){if(a[1]==="nth"){a[2]||k.error(a[0]),a[2]=a[2].replace(/^\+|\s*/g,"");var b=/(-?)(\d*)(?:n([+\-]?\d*))?/.exec(a[2]==="even"&&"2n"||a[2]==="odd"&&"2n+1"||!/\D/.test(a[2])&&"0n+"+a[2]||a[2]);a[2]=b[1]+(b[2]||1)-0,a[3]=b[3]-0}else a[2]&&k.error(a[0]);a[0]=d++;return a},ATTR:function(a,b,c,d,e,f){var g=a[1]=a[1].replace(i,"");!f&&l.attrMap[g]&&(a[1]=l.attrMap[g]),a[4]=(a[4]||a[5]||"").replace(i,""),a[2]==="~="&&(a[4]=" "+a[4]+" ");return a},PSEUDO:function(b,c,d,e,f){if(b[1]==="not")if((a.exec(b[3])||"").length>1||/^\w/.test(b[3]))b[3]=k(b[3],null,null,c);else{var g=k.filter(b[3],c,d,!0^f);d||e.push.apply(e,g);return!1}else if(l.match.POS.test(b[0])||l.match.CHILD.test(b[0]))return!0;return b},POS:function(a){a.unshift(!0);return a}},filters:{enabled:function(a){return a.disabled===!1&&a.type!=="hidden"},disabled:function(a){return a.disabled===!0},checked:function(a){return a.checked===!0},selected:function(a){a.parentNode&&a.parentNode.selectedIndex;return a.selected===!0},parent:function(a){return!!a.firstChild},empty:function(a){return!a.firstChild},has:function(a,b,c){return!!k(c[3],a).length},header:function(a){return/h\d/i.test(a.nodeName)},text:function(a){var b=a.getAttribute("type"),c=a.type;return a.nodeName.toLowerCase()==="input"&&"text"===c&&(b===c||b===null)},radio:function(a){return a.nodeName.toLowerCase()==="input"&&"radio"===a.type},checkbox:function(a){return a.nodeName.toLowerCase()==="input"&&"checkbox"===a.type},file:function(a){return a.nodeName.toLowerCase()==="input"&&"file"===a.type},password:function(a){return a.nodeName.toLowerCase()==="input"&&"password"===a.type},submit:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"submit"===a.type},image:function(a){return a.nodeName.toLowerCase()==="input"&&"image"===a.type},reset:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"reset"===a.type},button:function(a){var b=a.nodeName.toLowerCase();return b==="input"&&"button"===a.type||b==="button"},input:function(a){return/input|select|textarea|button/i.test(a.nodeName)},focus:function(a){return a===a.ownerDocument.activeElement}},setFilters:{first:function(a,b){return b===0},last:function(a,b,c,d){return b===d.length-1},even:function(a,b){return b%2===0},odd:function(a,b){return b%2===1},lt:function(a,b,c){return b<c[3]-0},gt:function(a,b,c){return b>c[3]-0},nth:function(a,b,c){return c[3]-0===b},eq:function(a,b,c){return c[3]-0===b}},filter:{PSEUDO:function(a,b,c,d){var e=b[1],f=l.filters[e];if(f)return f(a,c,b,d);if(e==="contains")return(a.textContent||a.innerText||k.getText([a])||"").indexOf(b[3])>=0;if(e==="not"){var g=b[3];for(var h=0,i=g.length;h<i;h++)if(g[h]===a)return!1;return!0}k.error(e)},CHILD:function(a,b){var c=b[1],d=a;switch(c){case"only":case"first":while(d=d.previousSibling)if(d.nodeType===1)return!1;if(c==="first")return!0;d=a;case"last":while(d=d.nextSibling)if(d.nodeType===1)return!1;return!0;case"nth":var e=b[2],f=b[3];if(e===1&&f===0)return!0;var g=b[0],h=a.parentNode;if(h&&(h.sizcache!==g||!a.nodeIndex)){var i=0;for(d=h.firstChild;d;d=d.nextSibling)d.nodeType===1&&(d.nodeIndex=++i);h.sizcache=g}var j=a.nodeIndex-f;return e===0?j===0:j%e===0&&j/e>=0}},ID:function(a,b){return a.nodeType===1&&a.getAttribute("id")===b},TAG:function(a,b){return b==="*"&&a.nodeType===1||a.nodeName.toLowerCase()===b},CLASS:function(a,b){return(" "+(a.className||a.getAttribute("class"))+" ").indexOf(b)>-1},ATTR:function(a,b){var c=b[1],d=l.attrHandle[c]?l.attrHandle[c](a):a[c]!=null?a[c]:a.getAttribute(c),e=d+"",f=b[2],g=b[4];return d==null?f==="!=":f==="="?e===g:f==="*="?e.indexOf(g)>=0:f==="~="?(" "+e+" ").indexOf(g)>=0:g?f==="!="?e!==g:f==="^="?e.indexOf(g)===0:f==="$="?e.substr(e.length-g.length)===g:f==="|="?e===g||e.substr(0,g.length+1)===g+"-":!1:e&&d!==!1},POS:function(a,b,c,d){var e=b[2],f=l.setFilters[e];if(f)return f(a,c,b,d)}}},m=l.match.POS,n=function(a,b){return"\\"+(b-0+1)};for(var o in l.match)l.match[o]=new RegExp(l.match[o].source+/(?![^\[]*\])(?![^\(]*\))/.source),l.leftMatch[o]=new RegExp(/(^(?:.|\r|\n)*?)/.source+l.match[o].source.replace(/\\(\d+)/g,n));var p=function(a,b){a=Array.prototype.slice.call(a,0);if(b){b.push.apply(b,a);return b}return a};try{Array.prototype.slice.call(c.documentElement.childNodes,0)[0].nodeType}catch(q){p=function(a,b){var c=0,d=b||[];if(e.call(a)==="[object Array]")Array.prototype.push.apply(d,a);else if(typeof a.length=="number")for(var f=a.length;c<f;c++)d.push(a[c]);else for(;a[c];c++)d.push(a[c]);return d}}var r,s;c.documentElement.compareDocumentPosition?r=function(a,b){if(a===b){g=!0;return 0}if(!a.compareDocumentPosition||!b.compareDocumentPosition)return a.compareDocumentPosition?-1:1;return a.compareDocumentPosition(b)&4?-1:1}:(r=function(a,b){if(a===b){g=!0;return 0}if(a.sourceIndex&&b.sourceIndex)return a.sourceIndex-b.sourceIndex;var c,d,e=[],f=[],h=a.parentNode,i=b.parentNode,j=h;if(h===i)return s(a,b);if(!h)return-1;if(!i)return 1;while(j)e.unshift(j),j=j.parentNode;j=i;while(j)f.unshift(j),j=j.parentNode;c=e.length,d=f.length;for(var k=0;k<c&&k<d;k++)if(e[k]!==f[k])return s(e[k],f[k]);return k===c?s(a,f[k],-1):s(e[k],b,1)},s=function(a,b,c){if(a===b)return c;var d=a.nextSibling;while(d){if(d===b)return-1;d=d.nextSibling}return 1}),k.getText=function(a){var b="",c;for(var d=0;a[d];d++)c=a[d],c.nodeType===3||c.nodeType===4?b+=c.nodeValue:c.nodeType!==8&&(b+=k.getText(c.childNodes));return b},function(){var a=c.createElement("div"),d="script"+(new Date).getTime(),e=c.documentElement;a.innerHTML="<a name='"+d+"'/>",e.insertBefore(a,e.firstChild),c.getElementById(d)&&(l.find.ID=function(a,c,d){if(typeof c.getElementById!="undefined"&&!d){var e=c.getElementById(a[1]);return e?e.id===a[1]||typeof e.getAttributeNode!="undefined"&&e.getAttributeNode("id").nodeValue===a[1]?[e]:b:[]}},l.filter.ID=function(a,b){var c=typeof a.getAttributeNode!="undefined"&&a.getAttributeNode("id");return a.nodeType===1&&c&&c.nodeValue===b}),e.removeChild(a),e=a=null}(),function(){var a=c.createElement("div");a.appendChild(c.createComment("")),a.getElementsByTagName("*").length>0&&(l.find.TAG=function(a,b){var c=b.getElementsByTagName(a[1]);if(a[1]==="*"){var d=[];for(var e=0;c[e];e++)c[e].nodeType===1&&d.push(c[e]);c=d}return c}),a.innerHTML="<a href='#'></a>",a.firstChild&&typeof a.firstChild.getAttribute!="undefined"&&a.firstChild.getAttribute("href")!=="#"&&(l.attrHandle.href=function(a){return a.getAttribute("href",2)}),a=null}(),c.querySelectorAll&&function(){var a=k,b=c.createElement("div"),d="__sizzle__";b.innerHTML="<p class='TEST'></p>";if(!b.querySelectorAll||b.querySelectorAll(".TEST").length!==0){k=function(b,e,f,g){e=e||c;if(!g&&!k.isXML(e)){var h=/^(\w+$)|^\.([\w\-]+$)|^#([\w\-]+$)/.exec(b);if(h&&(e.nodeType===1||e.nodeType===9)){if(h[1])return p(e.getElementsByTagName(b),f);if(h[2]&&l.find.CLASS&&e.getElementsByClassName)return p(e.getElementsByClassName(h[2]),f)}if(e.nodeType===9){if(b==="body"&&e.body)return p([e.body],f);if(h&&h[3]){var i=e.getElementById(h[3]);if(!i||!i.parentNode)return p([],f);if(i.id===h[3])return p([i],f)}try{return p(e.querySelectorAll(b),f)}catch(j){}}else if(e.nodeType===1&&e.nodeName.toLowerCase()!=="object"){var m=e,n=e.getAttribute("id"),o=n||d,q=e.parentNode,r=/^\s*[+~]/.test(b);n?o=o.replace(/'/g,"\\$&"):e.setAttribute("id",o),r&&q&&(e=e.parentNode);try{if(!r||q)return p(e.querySelectorAll("[id='"+o+"'] "+b),f)}catch(s){}finally{n||m.removeAttribute("id")}}}return a(b,e,f,g)};for(var e in a)k[e]=a[e];b=null}}(),function(){var a=c.documentElement,b=a.matchesSelector||a.mozMatchesSelector||a.webkitMatchesSelector||a.msMatchesSelector;if(b){var d=!b.call(c.createElement("div"),"div"),e=!1;try{b.call(c.documentElement,"[test!='']:sizzle")}catch(f){e=!0}k.matchesSelector=function(a,c){c=c.replace(/\=\s*([^'"\]]*)\s*\]/g,"='$1']");if(!k.isXML(a))try{if(e||!l.match.PSEUDO.test(c)&&!/!=/.test(c)){var f=b.call(a,c);if(f||!d||a.document&&a.document.nodeType!==11)return f}}catch(g){}return k(c,null,null,[a]).length>0}}}(),function(){var a=c.createElement("div");a.innerHTML="<div class='test e'></div><div class='test'></div>";if(!!a.getElementsByClassName&&a.getElementsByClassName("e").length!==0){a.lastChild.className="e";if(a.getElementsByClassName("e").length===1)return;l.order.splice(1,0,"CLASS"),l.find.CLASS=function(a,b,c){if(typeof b.getElementsByClassName!="undefined"&&!c)return b.getElementsByClassName(a[1])},a=null}}(),c.documentElement.contains?k.contains=function(a,b){return a!==b&&(a.contains?a.contains(b):!0)}:c.documentElement.compareDocumentPosition?k.contains=function(a,b){return!!(a.compareDocumentPosition(b)&16)}:k.contains=function(){return!1},k.isXML=function(a){var b=(a?a.ownerDocument||a:0).documentElement;return b?b.nodeName!=="HTML":!1};var v=function(a,b){var c,d=[],e="",f=b.nodeType?[b]:b;while(c=l.match.PSEUDO.exec(a))e+=c[0],a=a.replace(l.match.PSEUDO,"");a=l.relative[a]?a+"*":a;for(var g=0,h=f.length;g<h;g++)k(a,f[g],d);return k.filter(e,d)};f.find=k,f.expr=k.selectors,f.expr[":"]=f.expr.filters,f.unique=k.uniqueSort,f.text=k.getText,f.isXMLDoc=k.isXML,f.contains=k.contains}();var O=/Until$/,P=/^(?:parents|prevUntil|prevAll)/,Q=/,/,R=/^.[^:#\[\.,]*$/,S=Array.prototype.slice,T=f.expr.match.POS,U={children:!0,contents:!0,next:!0,prev:!0};f.fn.extend({find:function(a){var b=this,c,d;if(typeof a!="string")return f(a).filter(function(){for(c=0,d=b.length;c<d;c++)if(f.contains(b[c],this))return!0});var e=this.pushStack("","find",a),g,h,i;for(c=0,d=this.length;c<d;c++){g=e.length,f.find(a,this[c],e);if(c>0)for(h=g;h<e.length;h++)for(i=0;i<g;i++)if(e[i]===e[h]){e.splice(h--,1);break}}return e},has:function(a){var b=f(a);return this.filter(function(){for(var a=0,c=b.length;a<c;a++)if(f.contains(this,b[a]))return!0})},not:function(a){return this.pushStack(W(this,a,!1),"not",a)},filter:function(a){return this.pushStack(W(this,a,!0),"filter",a)},is:function(a){return!!a&&(typeof a=="string"?f.filter(a,this).length>0:this.filter(a).length>0)},closest:function(a,b){var c=[],d,e,g=this[0];if(f.isArray(a)){var h,i,j={},k=1;if(g&&a.length){for(d=0,e=a.length;d<e;d++)i=a[d],j[i]||(j[i]=T.test(i)?f(i,b||this.context):i);while(g&&g.ownerDocument&&g!==b){for(i in j)h=j[i],(h.jquery?h.index(g)>-1:f(g).is(h))&&c.push({selector:i,elem:g,level:k});g=g.parentNode,k++}}return c}var l=T.test(a)||typeof a!="string"?f(a,b||this.context):0;for(d=0,e=this.length;d<e;d++){g=this[d];while(g){if(l?l.index(g)>-1:f.find.matchesSelector(g,a)){c.push(g);break}g=g.parentNode;if(!g||!g.ownerDocument||g===b||g.nodeType===11)break}}c=c.length>1?f.unique(c):c;return this.pushStack(c,"closest",a)},index:function(a){if(!a||typeof a=="string")return f.inArray(this[0],a?f(a):this.parent().children());return f.inArray(a.jquery?a[0]:a,this)},add:function(a,b){var c=typeof a=="string"?f(a,b):f.makeArray(a&&a.nodeType?[a]:a),d=f.merge(this.get(),c);return this.pushStack(V(c[0])||V(d[0])?d:f.unique(d))},andSelf:function(){return this.add(this.prevObject)}}),f.each({parent:function(a){var b=a.parentNode;return b&&b.nodeType!==11?b:null},parents:function(a){return f.dir(a,"parentNode")},parentsUntil:function(a,b,c){return f.dir(a,"parentNode",c)},next:function(a){return f.nth(a,2,"nextSibling")},prev:function(a){return f.nth(a,2,"previousSibling")},nextAll:function(a){return f.dir(a,"nextSibling")},prevAll:function(a){return f.dir(a,"previousSibling")},nextUntil:function(a,b,c){return f.dir(a,"nextSibling",c)},prevUntil:function(a,b,c){return f.dir(a,"previousSibling",c)},siblings:function(a){return f.sibling(a.parentNode.firstChild,a)},children:function(a){return f.sibling(a.firstChild)},contents:function(a){return f.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:f.makeArray(a.childNodes)}},function(a,b){f.fn[a]=function(c,d){var e=f.map(this,b,c),g=S.call(arguments);O.test(a)||(d=c),d&&typeof d=="string"&&(e=f.filter(d,e)),e=this.length>1&&!U[a]?f.unique(e):e,(this.length>1||Q.test(d))&&P.test(a)&&(e=e.reverse());return this.pushStack(e,a,g.join(","))}}),f.extend({filter:function(a,b,c){c&&(a=":not("+a+")");return b.length===1?f.find.matchesSelector(b[0],a)?[b[0]]:[]:f.find.matches(a,b)},dir:function(a,c,d){var e=[],g=a[c];while(g&&g.nodeType!==9&&(d===b||g.nodeType!==1||!f(g).is(d)))g.nodeType===1&&e.push(g),g=g[c];return e},nth:function(a,b,c,d){b=b||1;var e=0;for(;a;a=a[c])if(a.nodeType===1&&++e===b)break;return a},sibling:function(a,b){var c=[];for(;a;a=a.nextSibling)a.nodeType===1&&a!==b&&c.push(a);return c}});var X=/ jQuery\d+="(?:\d+|null)"/g,Y=/^\s+/,Z=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/ig,$=/<([\w:]+)/,_=/<tbody/i,ba=/<|&#?\w+;/,bb=/<(?:script|object|embed|option|style)/i,bc=/checked\s*(?:[^=]|=\s*.checked.)/i,bd=/\/(java|ecma)script/i,be=/^\s*<!(?:\[CDATA\[|\-\-)/,bf={option:[1,"<select multiple='multiple'>","</select>"],legend:[1,"<fieldset>","</fieldset>"],thead:[1,"<table>","</table>"],tr:[2,"<table><tbody>","</tbody></table>"],td:[3,"<table><tbody><tr>","</tr></tbody></table>"],col:[2,"<table><tbody></tbody><colgroup>","</colgroup></table>"],area:[1,"<map>","</map>"],_default:[0,"",""]};bf.optgroup=bf.option,bf.tbody=bf.tfoot=bf.colgroup=bf.caption=bf.thead,bf.th=bf.td,f.support.htmlSerialize||(bf._default=[1,"div<div>","</div>"]),f.fn.extend({text:function(a){if(f.isFunction(a))return this.each(function(b){var c=f(this);c.text(a.call(this,b,c.text()))});if(typeof a!="object"&&a!==b)return this.empty().append((this[0]&&this[0].ownerDocument||c).createTextNode(a));return f.text(this)},wrapAll:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapAll(a.call(this,b))});if(this[0]){var b=f(a,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstChild&&a.firstChild.nodeType===1)a=a.firstChild;return a}).append(this)}return this},wrapInner:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapInner(a.call(this,b))});return this.each(function(){var b=f(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){return this.each(function(){f(this).wrapAll(a)})},unwrap:function(){return this.parent().each(function(){f.nodeName(this,"body")||f(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this)});if(arguments.length){var a=f(arguments[0]);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this.nextSibling)});if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,f(arguments[0]).toArray());return a}},remove:function(a,b){for(var c=0,d;(d=this[c])!=null;c++)if(!a||f.filter(a,[d]).length)!b&&d.nodeType===1&&(f.cleanData(d.getElementsByTagName("*")),f.cleanData([d])),d.parentNode&&d.parentNode.removeChild(d);return this},empty:function(){for(var a=0,b;(b=this[a])!=null;a++){b.nodeType===1&&f.cleanData(b.getElementsByTagName("*"));while(b.firstChild)b.removeChild(b.firstChild)}return this},clone:function(a,b){a=a==null?!1:a,b=b==null?a:b;return this.map(function(){return f.clone(this,a,b)})},html:function(a){if(a===b)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(X,""):null;if(typeof a=="string"&&!bb.test(a)&&(f.support.leadingWhitespace||!Y.test(a))&&!bf[($.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Z,"<$1></$2>");try{for(var c=0,d=this.length;c<d;c++)this[c].nodeType===1&&(f.cleanData(this[c].getElementsByTagName("*")),this[c].innerHTML=a)}catch(e){this.empty().append(a)}}else f.isFunction(a)?this.each(function(b){var c=f(this);c.html(a.call(this,b,c.html()))}):this.empty().append(a);return this},replaceWith:function(a){if(this[0]&&this[0].parentNode){if(f.isFunction(a))return this.each(function(b){var c=f(this),d=c.html();c.replaceWith(a.call(this,b,d))});typeof a!="string"&&(a=f(a).detach());return this.each(function(){var b=this.nextSibling,c=this.parentNode;f(this).remove(),b?f(b).before(a):f(c).append(a)})}return this.length?this.pushStack(f(f.isFunction(a)?a():a),"replaceWith",a):this},detach:function(a){return this.remove(a,!0)},domManip:function(a,c,d){var e,g,h,i,j=a[0],k=[];if(!f.support.checkClone&&arguments.length===3&&typeof j=="string"&&bc.test(j))return this.each(function(){f(this).domManip(a,c,d,!0)});if(f.isFunction(j))return this.each(function(e){var g=f(this);a[0]=j.call(this,e,c?g.html():b),g.domManip(a,c,d)});if(this[0]){i=j&&j.parentNode,f.support.parentNode&&i&&i.nodeType===11&&i.childNodes.length===this.length?e={fragment:i}:e=f.buildFragment(a,this,k),h=e.fragment,h.childNodes.length===1?g=h=h.firstChild:g=h.firstChild;if(g){c=c&&f.nodeName(g,"tr");for(var l=0,m=this.length,n=m-1;l<m;l++)d.call(c?bg(this[l],g):this[l],e.cacheable||m>1&&l<n?f.clone(h,!0,!0):h)}k.length&&f.each(k,bm)}return this}}),f.buildFragment=function(a,b,d){var e,g,h,i;b&&b[0]&&(i=b[0].ownerDocument||b[0]),i.createDocumentFragment||(i=c),a.length===1&&typeof a[0]=="string"&&a[0].length<512&&i===c&&a[0].charAt(0)==="<"&&!bb.test(a[0])&&(f.support.checkClone||!bc.test(a[0]))&&(g=!0,h=f.fragments[a[0]],h&&h!==1&&(e=h)),e||(e=i.createDocumentFragment(),f.clean(a,i,e,d)),g&&(f.fragments[a[0]]=h?e:1);return{fragment:e,cacheable:g}},f.fragments={},f.each({appendTo:"append",prependTo:"prepend",insertBefore:"before",insertAfter:"after",replaceAll:"replaceWith"},function(a,b){f.fn[a]=function(c){var d=[],e=f(c),g=this.length===1&&this[0].parentNode;if(g&&g.nodeType===11&&g.childNodes.length===1&&e.length===1){e[b](this[0]);return this}for(var h=0,i=e.length;h<i;h++){var j=(h>0?this.clone(!0):this).get();f(e[h])[b](j),d=d.concat(j -)}return this.pushStack(d,a,e.selector)}}),f.extend({clone:function(a,b,c){var d=a.cloneNode(!0),e,g,h;if((!f.support.noCloneEvent||!f.support.noCloneChecked)&&(a.nodeType===1||a.nodeType===11)&&!f.isXMLDoc(a)){bi(a,d),e=bj(a),g=bj(d);for(h=0;e[h];++h)bi(e[h],g[h])}if(b){bh(a,d);if(c){e=bj(a),g=bj(d);for(h=0;e[h];++h)bh(e[h],g[h])}}e=g=null;return d},clean:function(a,b,d,e){var g;b=b||c,typeof b.createElement=="undefined"&&(b=b.ownerDocument||b[0]&&b[0].ownerDocument||c);var h=[],i;for(var j=0,k;(k=a[j])!=null;j++){typeof k=="number"&&(k+="");if(!k)continue;if(typeof k=="string")if(!ba.test(k))k=b.createTextNode(k);else{k=k.replace(Z,"<$1></$2>");var l=($.exec(k)||["",""])[1].toLowerCase(),m=bf[l]||bf._default,n=m[0],o=b.createElement("div");o.innerHTML=m[1]+k+m[2];while(n--)o=o.lastChild;if(!f.support.tbody){var p=_.test(k),q=l==="table"&&!p?o.firstChild&&o.firstChild.childNodes:m[1]==="<table>"&&!p?o.childNodes:[];for(i=q.length-1;i>=0;--i)f.nodeName(q[i],"tbody")&&!q[i].childNodes.length&&q[i].parentNode.removeChild(q[i])}!f.support.leadingWhitespace&&Y.test(k)&&o.insertBefore(b.createTextNode(Y.exec(k)[0]),o.firstChild),k=o.childNodes}var r;if(!f.support.appendChecked)if(k[0]&&typeof (r=k.length)=="number")for(i=0;i<r;i++)bl(k[i]);else bl(k);k.nodeType?h.push(k):h=f.merge(h,k)}if(d){g=function(a){return!a.type||bd.test(a.type)};for(j=0;h[j];j++)if(e&&f.nodeName(h[j],"script")&&(!h[j].type||h[j].type.toLowerCase()==="text/javascript"))e.push(h[j].parentNode?h[j].parentNode.removeChild(h[j]):h[j]);else{if(h[j].nodeType===1){var s=f.grep(h[j].getElementsByTagName("script"),g);h.splice.apply(h,[j+1,0].concat(s))}d.appendChild(h[j])}}return h},cleanData:function(a){var b,c,d=f.cache,e=f.expando,g=f.event.special,h=f.support.deleteExpando;for(var i=0,j;(j=a[i])!=null;i++){if(j.nodeName&&f.noData[j.nodeName.toLowerCase()])continue;c=j[f.expando];if(c){b=d[c]&&d[c][e];if(b&&b.events){for(var k in b.events)g[k]?f.event.remove(j,k):f.removeEvent(j,k,b.handle);b.handle&&(b.handle.elem=null)}h?delete j[f.expando]:j.removeAttribute&&j.removeAttribute(f.expando),delete d[c]}}}});var bn=/alpha\([^)]*\)/i,bo=/opacity=([^)]*)/,bp=/([A-Z]|^ms)/g,bq=/^-?\d+(?:px)?$/i,br=/^-?\d/,bs=/^[+\-]=/,bt=/[^+\-\.\de]+/g,bu={position:"absolute",visibility:"hidden",display:"block"},bv=["Left","Right"],bw=["Top","Bottom"],bx,by,bz;f.fn.css=function(a,c){if(arguments.length===2&&c===b)return this;return f.access(this,a,c,!0,function(a,c,d){return d!==b?f.style(a,c,d):f.css(a,c)})},f.extend({cssHooks:{opacity:{get:function(a,b){if(b){var c=bx(a,"opacity","opacity");return c===""?"1":c}return a.style.opacity}}},cssNumber:{fillOpacity:!0,fontWeight:!0,lineHeight:!0,opacity:!0,orphans:!0,widows:!0,zIndex:!0,zoom:!0},cssProps:{"float":f.support.cssFloat?"cssFloat":"styleFloat"},style:function(a,c,d,e){if(!!a&&a.nodeType!==3&&a.nodeType!==8&&!!a.style){var g,h,i=f.camelCase(c),j=a.style,k=f.cssHooks[i];c=f.cssProps[i]||i;if(d===b){if(k&&"get"in k&&(g=k.get(a,!1,e))!==b)return g;return j[c]}h=typeof d;if(h==="number"&&isNaN(d)||d==null)return;h==="string"&&bs.test(d)&&(d=+d.replace(bt,"")+parseFloat(f.css(a,c)),h="number"),h==="number"&&!f.cssNumber[i]&&(d+="px");if(!k||!("set"in k)||(d=k.set(a,d))!==b)try{j[c]=d}catch(l){}}},css:function(a,c,d){var e,g;c=f.camelCase(c),g=f.cssHooks[c],c=f.cssProps[c]||c,c==="cssFloat"&&(c="float");if(g&&"get"in g&&(e=g.get(a,!0,d))!==b)return e;if(bx)return bx(a,c)},swap:function(a,b,c){var d={};for(var e in b)d[e]=a.style[e],a.style[e]=b[e];c.call(a);for(e in b)a.style[e]=d[e]}}),f.curCSS=f.css,f.each(["height","width"],function(a,b){f.cssHooks[b]={get:function(a,c,d){var e;if(c){if(a.offsetWidth!==0)return bA(a,b,d);f.swap(a,bu,function(){e=bA(a,b,d)});return e}},set:function(a,b){if(!bq.test(b))return b;b=parseFloat(b);if(b>=0)return b+"px"}}}),f.support.opacity||(f.cssHooks.opacity={get:function(a,b){return bo.test((b&&a.currentStyle?a.currentStyle.filter:a.style.filter)||"")?parseFloat(RegExp.$1)/100+"":b?"1":""},set:function(a,b){var c=a.style,d=a.currentStyle;c.zoom=1;var e=f.isNaN(b)?"":"alpha(opacity="+b*100+")",g=d&&d.filter||c.filter||"";c.filter=bn.test(g)?g.replace(bn,e):g+" "+e}}),f(function(){f.support.reliableMarginRight||(f.cssHooks.marginRight={get:function(a,b){var c;f.swap(a,{display:"inline-block"},function(){b?c=bx(a,"margin-right","marginRight"):c=a.style.marginRight});return c}})}),c.defaultView&&c.defaultView.getComputedStyle&&(by=function(a,c){var d,e,g;c=c.replace(bp,"-$1").toLowerCase();if(!(e=a.ownerDocument.defaultView))return b;if(g=e.getComputedStyle(a,null))d=g.getPropertyValue(c),d===""&&!f.contains(a.ownerDocument.documentElement,a)&&(d=f.style(a,c));return d}),c.documentElement.currentStyle&&(bz=function(a,b){var c,d=a.currentStyle&&a.currentStyle[b],e=a.runtimeStyle&&a.runtimeStyle[b],f=a.style;!bq.test(d)&&br.test(d)&&(c=f.left,e&&(a.runtimeStyle.left=a.currentStyle.left),f.left=b==="fontSize"?"1em":d||0,d=f.pixelLeft+"px",f.left=c,e&&(a.runtimeStyle.left=e));return d===""?"auto":d}),bx=by||bz,f.expr&&f.expr.filters&&(f.expr.filters.hidden=function(a){var b=a.offsetWidth,c=a.offsetHeight;return b===0&&c===0||!f.support.reliableHiddenOffsets&&(a.style.display||f.css(a,"display"))==="none"},f.expr.filters.visible=function(a){return!f.expr.filters.hidden(a)});var bB=/%20/g,bC=/\[\]$/,bD=/\r?\n/g,bE=/#.*$/,bF=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,bG=/^(?:color|date|datetime|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,bH=/^(?:about|app|app\-storage|.+\-extension|file|widget):$/,bI=/^(?:GET|HEAD)$/,bJ=/^\/\//,bK=/\?/,bL=/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,bM=/^(?:select|textarea)/i,bN=/\s+/,bO=/([?&])_=[^&]*/,bP=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+))?)?/,bQ=f.fn.load,bR={},bS={},bT,bU;try{bT=e.href}catch(bV){bT=c.createElement("a"),bT.href="",bT=bT.href}bU=bP.exec(bT.toLowerCase())||[],f.fn.extend({load:function(a,c,d){if(typeof a!="string"&&bQ)return bQ.apply(this,arguments);if(!this.length)return this;var e=a.indexOf(" ");if(e>=0){var g=a.slice(e,a.length);a=a.slice(0,e)}var h="GET";c&&(f.isFunction(c)?(d=c,c=b):typeof c=="object"&&(c=f.param(c,f.ajaxSettings.traditional),h="POST"));var i=this;f.ajax({url:a,type:h,dataType:"html",data:c,complete:function(a,b,c){c=a.responseText,a.isResolved()&&(a.done(function(a){c=a}),i.html(g?f("<div>").append(c.replace(bL,"")).find(g):c)),d&&i.each(d,[c,b,a])}});return this},serialize:function(){return f.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?f.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||bM.test(this.nodeName)||bG.test(this.type))}).map(function(a,b){var c=f(this).val();return c==null?null:f.isArray(c)?f.map(c,function(a,c){return{name:b.name,value:a.replace(bD,"\r\n")}}):{name:b.name,value:c.replace(bD,"\r\n")}}).get()}}),f.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){f.fn[b]=function(a){return this.bind(b,a)}}),f.each(["get","post"],function(a,c){f[c]=function(a,d,e,g){f.isFunction(d)&&(g=g||e,e=d,d=b);return f.ajax({type:c,url:a,data:d,success:e,dataType:g})}}),f.extend({getScript:function(a,c){return f.get(a,b,c,"script")},getJSON:function(a,b,c){return f.get(a,b,c,"json")},ajaxSetup:function(a,b){b?f.extend(!0,a,f.ajaxSettings,b):(b=a,a=f.extend(!0,f.ajaxSettings,b));for(var c in{context:1,url:1})c in b?a[c]=b[c]:c in f.ajaxSettings&&(a[c]=f.ajaxSettings[c]);return a},ajaxSettings:{url:bT,isLocal:bH.test(bU[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":"*/*"},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":a.String,"text html":!0,"text json":f.parseJSON,"text xml":f.parseXML}},ajaxPrefilter:bW(bR),ajaxTransport:bW(bS),ajax:function(a,c){function w(a,c,l,m){if(s!==2){s=2,q&&clearTimeout(q),p=b,n=m||"",v.readyState=a?4:0;var o,r,u,w=l?bZ(d,v,l):b,x,y;if(a>=200&&a<300||a===304){if(d.ifModified){if(x=v.getResponseHeader("Last-Modified"))f.lastModified[k]=x;if(y=v.getResponseHeader("Etag"))f.etag[k]=y}if(a===304)c="notmodified",o=!0;else try{r=b$(d,w),c="success",o=!0}catch(z){c="parsererror",u=z}}else{u=c;if(!c||a)c="error",a<0&&(a=0)}v.status=a,v.statusText=c,o?h.resolveWith(e,[r,c,v]):h.rejectWith(e,[v,c,u]),v.statusCode(j),j=b,t&&g.trigger("ajax"+(o?"Success":"Error"),[v,d,o?r:u]),i.resolveWith(e,[v,c]),t&&(g.trigger("ajaxComplete",[v,d]),--f.active||f.event.trigger("ajaxStop"))}}typeof a=="object"&&(c=a,a=b),c=c||{};var d=f.ajaxSetup({},c),e=d.context||d,g=e!==d&&(e.nodeType||e instanceof f)?f(e):f.event,h=f.Deferred(),i=f._Deferred(),j=d.statusCode||{},k,l={},m={},n,o,p,q,r,s=0,t,u,v={readyState:0,setRequestHeader:function(a,b){if(!s){var c=a.toLowerCase();a=m[c]=m[c]||a,l[a]=b}return this},getAllResponseHeaders:function(){return s===2?n:null},getResponseHeader:function(a){var c;if(s===2){if(!o){o={};while(c=bF.exec(n))o[c[1].toLowerCase()]=c[2]}c=o[a.toLowerCase()]}return c===b?null:c},overrideMimeType:function(a){s||(d.mimeType=a);return this},abort:function(a){a=a||"abort",p&&p.abort(a),w(0,a);return this}};h.promise(v),v.success=v.done,v.error=v.fail,v.complete=i.done,v.statusCode=function(a){if(a){var b;if(s<2)for(b in a)j[b]=[j[b],a[b]];else b=a[v.status],v.then(b,b)}return this},d.url=((a||d.url)+"").replace(bE,"").replace(bJ,bU[1]+"//"),d.dataTypes=f.trim(d.dataType||"*").toLowerCase().split(bN),d.crossDomain==null&&(r=bP.exec(d.url.toLowerCase()),d.crossDomain=!(!r||r[1]==bU[1]&&r[2]==bU[2]&&(r[3]||(r[1]==="http:"?80:443))==(bU[3]||(bU[1]==="http:"?80:443)))),d.data&&d.processData&&typeof d.data!="string"&&(d.data=f.param(d.data,d.traditional)),bX(bR,d,c,v);if(s===2)return!1;t=d.global,d.type=d.type.toUpperCase(),d.hasContent=!bI.test(d.type),t&&f.active++===0&&f.event.trigger("ajaxStart");if(!d.hasContent){d.data&&(d.url+=(bK.test(d.url)?"&":"?")+d.data),k=d.url;if(d.cache===!1){var x=f.now(),y=d.url.replace(bO,"$1_="+x);d.url=y+(y===d.url?(bK.test(d.url)?"&":"?")+"_="+x:"")}}(d.data&&d.hasContent&&d.contentType!==!1||c.contentType)&&v.setRequestHeader("Content-Type",d.contentType),d.ifModified&&(k=k||d.url,f.lastModified[k]&&v.setRequestHeader("If-Modified-Since",f.lastModified[k]),f.etag[k]&&v.setRequestHeader("If-None-Match",f.etag[k])),v.setRequestHeader("Accept",d.dataTypes[0]&&d.accepts[d.dataTypes[0]]?d.accepts[d.dataTypes[0]]+(d.dataTypes[0]!=="*"?", */*; q=0.01":""):d.accepts["*"]);for(u in d.headers)v.setRequestHeader(u,d.headers[u]);if(d.beforeSend&&(d.beforeSend.call(e,v,d)===!1||s===2)){v.abort();return!1}for(u in{success:1,error:1,complete:1})v[u](d[u]);p=bX(bS,d,c,v);if(!p)w(-1,"No Transport");else{v.readyState=1,t&&g.trigger("ajaxSend",[v,d]),d.async&&d.timeout>0&&(q=setTimeout(function(){v.abort("timeout")},d.timeout));try{s=1,p.send(l,w)}catch(z){status<2?w(-1,z):f.error(z)}}return v},param:function(a,c){var d=[],e=function(a,b){b=f.isFunction(b)?b():b,d[d.length]=encodeURIComponent(a)+"="+encodeURIComponent(b)};c===b&&(c=f.ajaxSettings.traditional);if(f.isArray(a)||a.jquery&&!f.isPlainObject(a))f.each(a,function(){e(this.name,this.value)});else for(var g in a)bY(g,a[g],c,e);return d.join("&").replace(bB,"+")}}),f.extend({active:0,lastModified:{},etag:{}});var b_=f.now(),ca=/(\=)\?(&|$)|\?\?/i;f.ajaxSetup({jsonp:"callback",jsonpCallback:function(){return f.expando+"_"+b_++}}),f.ajaxPrefilter("json jsonp",function(b,c,d){var e=b.contentType==="application/x-www-form-urlencoded"&&typeof b.data=="string";if(b.dataTypes[0]==="jsonp"||b.jsonp!==!1&&(ca.test(b.url)||e&&ca.test(b.data))){var g,h=b.jsonpCallback=f.isFunction(b.jsonpCallback)?b.jsonpCallback():b.jsonpCallback,i=a[h],j=b.url,k=b.data,l="$1"+h+"$2";b.jsonp!==!1&&(j=j.replace(ca,l),b.url===j&&(e&&(k=k.replace(ca,l)),b.data===k&&(j+=(/\?/.test(j)?"&":"?")+b.jsonp+"="+h))),b.url=j,b.data=k,a[h]=function(a){g=[a]},d.always(function(){a[h]=i,g&&f.isFunction(i)&&a[h](g[0])}),b.converters["script json"]=function(){g||f.error(h+" was not called");return g[0]},b.dataTypes[0]="json";return"script"}}),f.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(a){f.globalEval(a);return a}}}),f.ajaxPrefilter("script",function(a){a.cache===b&&(a.cache=!1),a.crossDomain&&(a.type="GET",a.global=!1)}),f.ajaxTransport("script",function(a){if(a.crossDomain){var d,e=c.head||c.getElementsByTagName("head")[0]||c.documentElement;return{send:function(f,g){d=c.createElement("script"),d.async="async",a.scriptCharset&&(d.charset=a.scriptCharset),d.src=a.url,d.onload=d.onreadystatechange=function(a,c){if(c||!d.readyState||/loaded|complete/.test(d.readyState))d.onload=d.onreadystatechange=null,e&&d.parentNode&&e.removeChild(d),d=b,c||g(200,"success")},e.insertBefore(d,e.firstChild)},abort:function(){d&&d.onload(0,1)}}}});var cb=a.ActiveXObject?function(){for(var a in cd)cd[a](0,1)}:!1,cc=0,cd;f.ajaxSettings.xhr=a.ActiveXObject?function(){return!this.isLocal&&ce()||cf()}:ce,function(a){f.extend(f.support,{ajax:!!a,cors:!!a&&"withCredentials"in a})}(f.ajaxSettings.xhr()),f.support.ajax&&f.ajaxTransport(function(c){if(!c.crossDomain||f.support.cors){var d;return{send:function(e,g){var h=c.xhr(),i,j;c.username?h.open(c.type,c.url,c.async,c.username,c.password):h.open(c.type,c.url,c.async);if(c.xhrFields)for(j in c.xhrFields)h[j]=c.xhrFields[j];c.mimeType&&h.overrideMimeType&&h.overrideMimeType(c.mimeType),!c.crossDomain&&!e["X-Requested-With"]&&(e["X-Requested-With"]="XMLHttpRequest");try{for(j in e)h.setRequestHeader(j,e[j])}catch(k){}h.send(c.hasContent&&c.data||null),d=function(a,e){var j,k,l,m,n;try{if(d&&(e||h.readyState===4)){d=b,i&&(h.onreadystatechange=f.noop,cb&&delete cd[i]);if(e)h.readyState!==4&&h.abort();else{j=h.status,l=h.getAllResponseHeaders(),m={},n=h.responseXML,n&&n.documentElement&&(m.xml=n),m.text=h.responseText;try{k=h.statusText}catch(o){k=""}!j&&c.isLocal&&!c.crossDomain?j=m.text?200:404:j===1223&&(j=204)}}}catch(p){e||g(-1,p)}m&&g(j,k,m,l)},!c.async||h.readyState===4?d():(i=++cc,cb&&(cd||(cd={},f(a).unload(cb)),cd[i]=d),h.onreadystatechange=d)},abort:function(){d&&d(0,1)}}}});var cg={},ch,ci,cj=/^(?:toggle|show|hide)$/,ck=/^([+\-]=)?([\d+.\-]+)([a-z%]*)$/i,cl,cm=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]],cn,co=a.webkitRequestAnimationFrame||a.mozRequestAnimationFrame||a.oRequestAnimationFrame;f.fn.extend({show:function(a,b,c){var d,e;if(a||a===0)return this.animate(cr("show",3),a,b,c);for(var g=0,h=this.length;g<h;g++)d=this[g],d.style&&(e=d.style.display,!f._data(d,"olddisplay")&&e==="none"&&(e=d.style.display=""),e===""&&f.css(d,"display")==="none"&&f._data(d,"olddisplay",cs(d.nodeName)));for(g=0;g<h;g++){d=this[g];if(d.style){e=d.style.display;if(e===""||e==="none")d.style.display=f._data(d,"olddisplay")||""}}return this},hide:function(a,b,c){if(a||a===0)return this.animate(cr("hide",3),a,b,c);for(var d=0,e=this.length;d<e;d++)if(this[d].style){var g=f.css(this[d],"display");g!=="none"&&!f._data(this[d],"olddisplay")&&f._data(this[d],"olddisplay",g)}for(d=0;d<e;d++)this[d].style&&(this[d].style.display="none");return this},_toggle:f.fn.toggle,toggle:function(a,b,c){var d=typeof a=="boolean";f.isFunction(a)&&f.isFunction(b)?this._toggle.apply(this,arguments):a==null||d?this.each(function(){var b=d?a:f(this).is(":hidden");f(this)[b?"show":"hide"]()}):this.animate(cr("toggle",3),a,b,c);return this},fadeTo:function(a,b,c,d){return this.filter(":hidden").css("opacity",0).show().end().animate({opacity:b},a,c,d)},animate:function(a,b,c,d){var e=f.speed(b,c,d);if(f.isEmptyObject(a))return this.each(e.complete,[!1]);a=f.extend({},a);return this[e.queue===!1?"each":"queue"](function(){e.queue===!1&&f._mark(this);var b=f.extend({},e),c=this.nodeType===1,d=c&&f(this).is(":hidden"),g,h,i,j,k,l,m,n,o;b.animatedProperties={};for(i in a){g=f.camelCase(i),i!==g&&(a[g]=a[i],delete a[i]),h=a[g],f.isArray(h)?(b.animatedProperties[g]=h[1],h=a[g]=h[0]):b.animatedProperties[g]=b.specialEasing&&b.specialEasing[g]||b.easing||"swing";if(h==="hide"&&d||h==="show"&&!d)return b.complete.call(this);c&&(g==="height"||g==="width")&&(b.overflow=[this.style.overflow,this.style.overflowX,this.style.overflowY],f.css(this,"display")==="inline"&&f.css(this,"float")==="none"&&(f.support.inlineBlockNeedsLayout?(j=cs(this.nodeName),j==="inline"?this.style.display="inline-block":(this.style.display="inline",this.style.zoom=1)):this.style.display="inline-block"))}b.overflow!=null&&(this.style.overflow="hidden");for(i in a)k=new f.fx(this,b,i),h=a[i],cj.test(h)?k[h==="toggle"?d?"show":"hide":h]():(l=ck.exec(h),m=k.cur(),l?(n=parseFloat(l[2]),o=l[3]||(f.cssNumber[i]?"":"px"),o!=="px"&&(f.style(this,i,(n||1)+o),m=(n||1)/k.cur()*m,f.style(this,i,m+o)),l[1]&&(n=(l[1]==="-="?-1:1)*n+m),k.custom(m,n,o)):k.custom(m,h,""));return!0})},stop:function(a,b){a&&this.queue([]),this.each(function(){var a=f.timers,c=a.length;b||f._unmark(!0,this);while(c--)a[c].elem===this&&(b&&a[c](!0),a.splice(c,1))}),b||this.dequeue();return this}}),f.each({slideDown:cr("show",1),slideUp:cr("hide",1),slideToggle:cr("toggle",1),fadeIn:{opacity:"show"},fadeOut:{opacity:"hide"},fadeToggle:{opacity:"toggle"}},function(a,b){f.fn[a]=function(a,c,d){return this.animate(b,a,c,d)}}),f.extend({speed:function(a,b,c){var d=a&&typeof a=="object"?f.extend({},a):{complete:c||!c&&b||f.isFunction(a)&&a,duration:a,easing:c&&b||b&&!f.isFunction(b)&&b};d.duration=f.fx.off?0:typeof d.duration=="number"?d.duration:d.duration in f.fx.speeds?f.fx.speeds[d.duration]:f.fx.speeds._default,d.old=d.complete,d.complete=function(a){f.isFunction(d.old)&&d.old.call(this),d.queue!==!1?f.dequeue(this):a!==!1&&f._unmark(this)};return d},easing:{linear:function(a,b,c,d){return c+d*a},swing:function(a,b,c,d){return(-Math.cos(a*Math.PI)/2+.5)*d+c}},timers:[],fx:function(a,b,c){this.options=b,this.elem=a,this.prop=c,b.orig=b.orig||{}}}),f.fx.prototype={update:function(){this.options.step&&this.options.step.call(this.elem,this.now,this),(f.fx.step[this.prop]||f.fx.step._default)(this)},cur:function(){if(this.elem[this.prop]!=null&&(!this.elem.style||this.elem.style[this.prop]==null))return this.elem[this.prop];var a,b=f.css(this.elem,this.prop);return isNaN(a=parseFloat(b))?!b||b==="auto"?0:b:a},custom:function(a,b,c){function h(a){return d.step(a)}var d=this,e=f.fx,g;this.startTime=cn||cp(),this.start=a,this.end=b,this.unit=c||this.unit||(f.cssNumber[this.prop]?"":"px"),this.now=this.start,this.pos=this.state=0,h.elem=this.elem,h()&&f.timers.push(h)&&!cl&&(co?(cl=!0,g=function(){cl&&(co(g),e.tick())},co(g)):cl=setInterval(e.tick,e.interval))},show:function(){this.options.orig[this.prop]=f.style(this.elem,this.prop),this.options.show=!0,this.custom(this.prop==="width"||this.prop==="height"?1:0,this.cur()),f(this.elem).show()},hide:function(){this.options.orig[this.prop]=f.style(this.elem,this.prop),this.options.hide=!0,this.custom(this.cur(),0)},step:function(a){var b=cn||cp(),c=!0,d=this.elem,e=this.options,g,h;if(a||b>=e.duration+this.startTime){this.now=this.end,this.pos=this.state=1,this.update(),e.animatedProperties[this.prop]=!0;for(g in e.animatedProperties)e.animatedProperties[g]!==!0&&(c=!1);if(c){e.overflow!=null&&!f.support.shrinkWrapBlocks&&f.each(["","X","Y"],function(a,b){d.style["overflow"+b]=e.overflow[a]}),e.hide&&f(d).hide();if(e.hide||e.show)for(var i in e.animatedProperties)f.style(d,i,e.orig[i]);e.complete.call(d)}return!1}e.duration==Infinity?this.now=b:(h=b-this.startTime,this.state=h/e.duration,this.pos=f.easing[e.animatedProperties[this.prop]](this.state,h,0,1,e.duration),this.now=this.start+(this.end-this.start)*this.pos),this.update();return!0}},f.extend(f.fx,{tick:function(){for(var a=f.timers,b=0;b<a.length;++b)a[b]()||a.splice(b--,1);a.length||f.fx.stop()},interval:13,stop:function(){clearInterval(cl),cl=null},speeds:{slow:600,fast:200,_default:400},step:{opacity:function(a){f.style(a.elem,"opacity",a.now)},_default:function(a){a.elem.style&&a.elem.style[a.prop]!=null?a.elem.style[a.prop]=(a.prop==="width"||a.prop==="height"?Math.max(0,a.now):a.now)+a.unit:a.elem[a.prop]=a.now}}}),f.expr&&f.expr.filters&&(f.expr.filters.animated=function(a){return f.grep(f.timers,function(b){return a===b.elem}).length});var ct=/^t(?:able|d|h)$/i,cu=/^(?:body|html)$/i;"getBoundingClientRect"in c.documentElement?f.fn.offset=function(a){var b=this[0],c;if(a)return this.each(function(b){f.offset.setOffset(this,a,b)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return f.offset.bodyOffset(b);try{c=b.getBoundingClientRect()}catch(d){}var e=b.ownerDocument,g=e.documentElement;if(!c||!f.contains(g,b))return c?{top:c.top,left:c.left}:{top:0,left:0};var h=e.body,i=cv(e),j=g.clientTop||h.clientTop||0,k=g.clientLeft||h.clientLeft||0,l=i.pageYOffset||f.support.boxModel&&g.scrollTop||h.scrollTop,m=i.pageXOffset||f.support.boxModel&&g.scrollLeft||h.scrollLeft,n=c.top+l-j,o=c.left+m-k;return{top:n,left:o}}:f.fn.offset=function(a){var b=this[0];if(a)return this.each(function(b){f.offset.setOffset(this,a,b)});if(!b||!b.ownerDocument)return null;if(b===b.ownerDocument.body)return f.offset.bodyOffset(b);f.offset.initialize();var c,d=b.offsetParent,e=b,g=b.ownerDocument,h=g.documentElement,i=g.body,j=g.defaultView,k=j?j.getComputedStyle(b,null):b.currentStyle,l=b.offsetTop,m=b.offsetLeft;while((b=b.parentNode)&&b!==i&&b!==h){if(f.offset.supportsFixedPosition&&k.position==="fixed")break;c=j?j.getComputedStyle(b,null):b.currentStyle,l-=b.scrollTop,m-=b.scrollLeft,b===d&&(l+=b.offsetTop,m+=b.offsetLeft,f.offset.doesNotAddBorder&&(!f.offset.doesAddBorderForTableAndCells||!ct.test(b.nodeName))&&(l+=parseFloat(c.borderTopWidth)||0,m+=parseFloat(c.borderLeftWidth)||0),e=d,d=b.offsetParent),f.offset.subtractsBorderForOverflowNotVisible&&c.overflow!=="visible"&&(l+=parseFloat(c.borderTopWidth)||0,m+=parseFloat(c.borderLeftWidth)||0),k=c}if(k.position==="relative"||k.position==="static")l+=i.offsetTop,m+=i.offsetLeft;f.offset.supportsFixedPosition&&k.position==="fixed"&&(l+=Math.max(h.scrollTop,i.scrollTop),m+=Math.max(h.scrollLeft,i.scrollLeft));return{top:l,left:m}},f.offset={initialize:function(){var a=c.body,b=c.createElement("div"),d,e,g,h,i=parseFloat(f.css(a,"marginTop"))||0,j="<div style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;'><div></div></div><table style='position:absolute;top:0;left:0;margin:0;border:5px solid #000;padding:0;width:1px;height:1px;' cellpadding='0' cellspacing='0'><tr><td></td></tr></table>";f.extend(b.style,{position:"absolute",top:0,left:0,margin:0,border:0,width:"1px",height:"1px",visibility:"hidden"}),b.innerHTML=j,a.insertBefore(b,a.firstChild),d=b.firstChild,e=d.firstChild,h=d.nextSibling.firstChild.firstChild,this.doesNotAddBorder=e.offsetTop!==5,this.doesAddBorderForTableAndCells=h.offsetTop===5,e.style.position="fixed",e.style.top="20px",this.supportsFixedPosition=e.offsetTop===20||e.offsetTop===15,e.style.position=e.style.top="",d.style.overflow="hidden",d.style.position="relative",this.subtractsBorderForOverflowNotVisible=e.offsetTop===-5,this.doesNotIncludeMarginInBodyOffset=a.offsetTop!==i,a.removeChild(b),f.offset.initialize=f.noop},bodyOffset:function(a){var b=a.offsetTop,c=a.offsetLeft;f.offset.initialize(),f.offset.doesNotIncludeMarginInBodyOffset&&(b+=parseFloat(f.css(a,"marginTop"))||0,c+=parseFloat(f.css(a,"marginLeft"))||0);return{top:b,left:c}},setOffset:function(a,b,c){var d=f.css(a,"position");d==="static"&&(a.style.position="relative");var e=f(a),g=e.offset(),h=f.css(a,"top"),i=f.css(a,"left"),j=(d==="absolute"||d==="fixed")&&f.inArray("auto",[h,i])>-1,k={},l={},m,n;j?(l=e.position(),m=l.top,n=l.left):(m=parseFloat(h)||0,n=parseFloat(i)||0),f.isFunction(b)&&(b=b.call(a,c,g)),b.top!=null&&(k.top=b.top-g.top+m),b.left!=null&&(k.left=b.left-g.left+n),"using"in b?b.using.call(a,k):e.css(k)}},f.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),c=this.offset(),d=cu.test(b[0].nodeName)?{top:0,left:0}:b.offset();c.top-=parseFloat(f.css(a,"marginTop"))||0,c.left-=parseFloat(f.css(a,"marginLeft"))||0,d.top+=parseFloat(f.css(b[0],"borderTopWidth"))||0,d.left+=parseFloat(f.css(b[0],"borderLeftWidth"))||0;return{top:c.top-d.top,left:c.left-d.left}},offsetParent:function(){return this.map(function(){var a=this.offsetParent||c.body;while(a&&!cu.test(a.nodeName)&&f.css(a,"position")==="static")a=a.offsetParent;return a})}}),f.each(["Left","Top"],function(a,c){var d="scroll"+c;f.fn[d]=function(c){var e,g;if(c===b){e=this[0];if(!e)return null;g=cv(e);return g?"pageXOffset"in g?g[a?"pageYOffset":"pageXOffset"]:f.support.boxModel&&g.document.documentElement[d]||g.document.body[d]:e[d]}return this.each(function(){g=cv(this),g?g.scrollTo(a?f(g).scrollLeft():c,a?c:f(g).scrollTop()):this[d]=c})}}),f.each(["Height","Width"],function(a,c){var d=c.toLowerCase();f.fn["inner"+c]=function(){var a=this[0];return a&&a.style?parseFloat(f.css(a,d,"padding")):null},f.fn["outer"+c]=function(a){var b=this[0];return b&&b.style?parseFloat(f.css(b,d,a?"margin":"border")):null},f.fn[d]=function(a){var e=this[0];if(!e)return a==null?null:this;if(f.isFunction(a))return this.each(function(b){var c=f(this);c[d](a.call(this,b,c[d]()))});if(f.isWindow(e)){var g=e.document.documentElement["client"+c];return e.document.compatMode==="CSS1Compat"&&g||e.document.body["client"+c]||g}if(e.nodeType===9)return Math.max(e.documentElement["client"+c],e.body["scroll"+c],e.documentElement["scroll"+c],e.body["offset"+c],e.documentElement["offset"+c]);if(a===b){var h=f.css(e,d),i=parseFloat(h);return f.isNaN(i)?h:i}return this.css(d,typeof a=="string"?a:a+"px")}}),a.jQuery=a.$=f})(window);
\ No newline at end of file diff --git a/docs/html/design/static/open_new_page.png b/docs/html/design/static/open_new_page.png Binary files differdeleted file mode 100644 index 6197e3a..0000000 --- a/docs/html/design/static/open_new_page.png +++ /dev/null diff --git a/docs/html/design/static/yui-3.3.0-reset-min.css b/docs/html/design/static/yui-3.3.0-reset-min.css deleted file mode 100644 index 00c3892..0000000 --- a/docs/html/design/static/yui-3.3.0-reset-min.css +++ /dev/null @@ -1,8 +0,0 @@ -/* -Copyright (c) 2010, Yahoo! Inc. All rights reserved. -Code licensed under the BSD License: -http://developer.yahoo.com/yui/license.html -version: 3.3.0 -build: 3167 -*/ -html{color:#000;background:#FFF;}body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,textarea,p,blockquote,th,td{margin:0;padding:0;}table{border-collapse:collapse;border-spacing:0;}fieldset,img{border:0;}address,caption,cite,code,dfn,em,strong,th,var{font-style:normal;font-weight:normal;}li{list-style:none;}caption,th{text-align:left;}h1,h2,h3,h4,h5,h6{font-size:100%;font-weight:normal;}q:before,q:after{content:'';}abbr,acronym{border:0;font-variant:normal;}sup{vertical-align:text-top;}sub{vertical-align:text-bottom;}input,textarea,select{font-family:inherit;font-size:inherit;font-weight:inherit;}input,textarea,select{*font-size:100%;}legend{color:#000;}
\ No newline at end of file diff --git a/docs/html/design/style/color.html b/docs/html/design/style/color.html deleted file mode 100644 index 893e09e..0000000 --- a/docs/html/design/style/color.html +++ /dev/null @@ -1,291 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Color - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - -<style> - .color-row { - width: 740px; - margin-left: 10px !important; - margin-right: 10px !important; - - display: box; - display: -webkit-box; - display: -moz-box; - - box-orient: horizontal; - -webkit-box-orient: horizontal; - -moz-box-orient: horizontal; - - cursor: pointer; - - user-select: none; - -webkit-user-select: none; - /* nested user-select in FF is broken as of Jan 2012, don't use it */ - } - - .color-row-container { - line-height: 0; /* to remove more top space in FF for -moz-box elements */ - } - - .color-row-container + .color-row-container { - margin-top: -10px !important; - } - - .color-row li { - margin-left: 0 !important; - position: relative; - list-style-type: none; - height: 80px; - display: block; - - box-flex: 1; - -webkit-box-flex: 1; - -moz-box-flex: 1; - } - - .color-row li:before { - display: none; - } - - .color-row li.thin { - height: 40px; - } - - .color-row li span { - display: none; - position: absolute; - top: -30px; - left: 50%; - margin-left: -2.5em; - width: 5em; - background-color: #fff; - padding: 10px; - font-weight: 600; - line-height: 20px; - text-align: center; - box-shadow: 0 5px 5px rgba(0,0,0,0.1); - cursor: text; - - user-select: text; - -webkit-user-select: text; - /* nested user-select in FF is broken as of Jan 2012, don't use it */ - } - - .color-row li:hover span { - display: block; - } - - /*.color-row li span:before { - color: #999; - content: 'copy '; - }*/ - - /* triangle callout */ - .color-row li span:after { - content: ''; - display: block; - position: absolute; - left: 50%; - bottom: -16px; - border: 8px solid transparent; - border-top-color: #fff; - width: 0; - height: 0; - margin-left: -8px; - } -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Color</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Use color primarily for emphasis. Choose colors that fit with your brand and provide good contrast -between visual components. Note that red and green may be indistinguishable to color-blind users.</p> - - <div class="color-row-container"> - <ul class="color-row"> - <li><span>#33b5e5</span></li> - <li><span>#aa66cc</span></li> - <li><span>#99cc00</span></li> - <li><span>#ffbb33</span></li> - <li><span>#ff4444</span></li> - </ul> - </div> - - <div class="color-row-container"> - <ul class="color-row"> - <li class="thin"><span>#0099cc</span></li> - <li class="thin"><span>#9933cc</span></li> - <li class="thin"><span>#669900</span></li> - <li class="thin"><span>#ff8800</span></li> - <li class="thin"><span>#cc0000</span></li> - </ul> - </div> - -<h2>Palette</h2> -<p>Blue is the standard accent color in Android's color palette. Each color has a corresponding darker -shade that can be used as a complement when needed.</p> -<p><a href="../static/download/color_swatches.zip">Download the swatches</a></p> - -<img src="../static/content/color_spectrum.png"> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - -<script> - $(document).ready(function() { - $('.color-row li').each(function() { - var color = $(this).text(); - $(this).css('background-color', color); - $(this).find('span') - .css('color', color) - .text(color.toUpperCase()); - }); - - }); -</script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/color.jd b/docs/html/design/style/color.jd new file mode 100644 index 0000000..e25f7c6 --- /dev/null +++ b/docs/html/design/style/color.jd @@ -0,0 +1,134 @@ +page.title=Color +@jd:body + +<style> + .color-row { + width: 740px; + margin-left: 10px !important; + margin-right: 10px !important; + + display: -webkit-box; + display: -moz-box; + display: box; + + -webkit-box-orient: horizontal; + -moz-box-orient: horizontal; + box-orient: horizontal; + + cursor: pointer; + + -webkit-user-select: none; + user-select: none; + /* nested user-select in FF is broken as of Jan 2012, don't use it */ + } + + .color-row-container { + line-height: 0; /* to remove more top space in FF for -moz-box elements */ + } + + .color-row-container + .color-row-container { + margin-top: -10px !important; + } + + .color-row li { + margin-left: 0 !important; + position: relative; + list-style-type: none; + height: 80px; + display: block; + + -webkit-box-flex: 1; + -moz-box-flex: 1; + box-flex: 1; + } + + .color-row li:before { + display: none; + } + + .color-row li.thin { + height: 40px; + } + + .color-row li span { + display: none; + position: absolute; + top: -30px; + left: 50%; + margin-left: -2.5em; + width: 5em; + background-color: #fff; + padding: 10px; + font-weight: 600; + line-height: 20px; + text-align: center; + box-shadow: 0 5px 5px rgba(0,0,0,0.1); + cursor: text; + + -webkit-user-select: text; + user-select: text; + /* nested user-select in FF is broken as of Jan 2012, don't use it */ + } + + .color-row li:hover span { + display: block; + } + + /* triangle callout */ + .color-row li span:after { + content: ''; + display: block; + position: absolute; + left: 50%; + bottom: -16px; + border: 8px solid transparent; + border-top-color: #fff; + width: 0; + height: 0; + margin-left: -8px; + } +</style> + +<p>Use color primarily for emphasis. Choose colors that fit with your brand and provide good contrast +between visual components. Note that red and green may be indistinguishable to color-blind users.</p> + + <div class="color-row-container"> + <ul class="color-row"> + <li><span>#33b5e5</span></li> + <li><span>#aa66cc</span></li> + <li><span>#99cc00</span></li> + <li><span>#ffbb33</span></li> + <li><span>#ff4444</span></li> + </ul> + </div> + + <div class="color-row-container"> + <ul class="color-row"> + <li class="thin"><span>#0099cc</span></li> + <li class="thin"><span>#9933cc</span></li> + <li class="thin"><span>#669900</span></li> + <li class="thin"><span>#ff8800</span></li> + <li class="thin"><span>#cc0000</span></li> + </ul> + </div> + +<h2 id="palette">Palette</h2> + +<p>Blue is the standard accent color in Android's color palette. Each color has a corresponding darker +shade that can be used as a complement when needed.</p> +<p><a href="https://dl-ssl.google.com/android/design/Android_Design_Color_Swatches_20120229.zip">Download the swatches</a></p> + +<img src="{@docRoot}design/media/color_spectrum.png"> + +<script> + $(document).ready(function() { + $('.color-row li').each(function() { + var color = $(this).text(); + $(this).css('background-color', color); + $(this).find('span') + .css('color', color) + .text(color.toUpperCase()); + }); + + }); +</script> diff --git a/docs/html/design/style/devices-displays.html b/docs/html/design/style/devices-displays.html deleted file mode 100644 index 9fba719..0000000 --- a/docs/html/design/style/devices-displays.html +++ /dev/null @@ -1,198 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Devices and Displays - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Devices and Displays</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Android powers millions of phones, tablets, and other devices in a wide variety of screen sizes and -form factors. By taking advantage of Android's flexible layout system, you can create apps that -gracefully scale from large tablets to smaller phones.</p> - -<img src="../static/content/devices_displays_main.png"> - -<div class="vspace size-2"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - -<h4>Be flexible</h4> -<p>Stretch and compress your layouts to accommodate various heights and widths.</p> - - </div> - <div class="layout-content-col span-5"> - -<h4>Optimize layouts</h4> -<p>On larger devices, take advantage of extra screen real estate. Create compound views that combine -multiple views to reveal more content and ease navigation.</p> - - </div> - <div class="layout-content-col span-4"> - -<h4>Assets for all</h4> -<p>Provide resources for different screen densities (<acronym title="Dots per inch">DPI</acronym>) to -ensure that your app looks great on any device.</p> - - </div> -</div> - -<div style="text-align:center"> - <img src="../static/content/devices_displays_density.png"> -</div> - -<h4>Strategies</h4> -<p>So where do you begin when designing for multiple screens? One approach is to work in the base -standard (medium size, <acronym title="Medium density (160 dpi)">MDPI</acronym>) and scale it up or -down for the other buckets. Another approach is to start with the device with the largest screen -size, and then scale down and figure out the UI compromises you'll need to make on smaller screens.</p> -<p>For more detailed information on this topic, please visit <a href="http://developer.android.com/guide/practices/screens_support.html">Supporting Multiple -Screens</a>.</p> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/devices-displays.jd b/docs/html/design/style/devices-displays.jd new file mode 100644 index 0000000..e5fe26d --- /dev/null +++ b/docs/html/design/style/devices-displays.jd @@ -0,0 +1,45 @@ +page.title=Devices and Displays +@jd:body + +<p>Android powers millions of phones, tablets, and other devices in a wide variety of screen sizes and +form factors. By taking advantage of Android's flexible layout system, you can create apps that +gracefully scale from large tablets to smaller phones.</p> + +<img src="{@docRoot}design/media/devices_displays_main.png"> + +<div class="vspace size-2"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + +<h4>Be flexible</h4> +<p>Stretch and compress your layouts to accommodate various heights and widths.</p> + + </div> + <div class="layout-content-col span-5"> + +<h4>Optimize layouts</h4> +<p>On larger devices, take advantage of extra screen real estate. Create compound views that combine +multiple views to reveal more content and ease navigation.</p> + + </div> + <div class="layout-content-col span-4"> + +<h4>Assets for all</h4> +<p>Provide resources for different screen densities (<acronym title="Dots per inch">DPI</acronym>) to +ensure that your app looks great on any device.</p> + + </div> +</div> + +<div style="text-align:center"> + <img src="{@docRoot}design/media/devices_displays_density.png"> +</div> + +<h4>Strategies</h4> +<p>So where do you begin when designing for multiple screens? One approach is to work in the base +standard (medium size, <acronym title="Medium density (160 dpi)">MDPI</acronym>) and scale it up or +down for the other buckets. Another approach is to start with the device with the largest screen +size, and then scale down and figure out the UI compromises you'll need to make on smaller screens.</p> +<p>For more detailed information on this topic, please visit <a href="http://developer.android.com/guide/practices/screens_support.html">Supporting Multiple +Screens</a>.</p> diff --git a/docs/html/design/style/iconography.html b/docs/html/design/style/iconography.html deleted file mode 100644 index 5d5d200..0000000 --- a/docs/html/design/style/iconography.html +++ /dev/null @@ -1,494 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Iconography - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Iconography</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<img src="../static/content/iconography_overview.png"> - -<p>An icon is a graphic that takes up a small portion of screen real estate and provides a quick, -intuitive representation of an action, a status, or an app.</p> - - - -<h2 id="launcher">Launcher</h2> - -<p>The launcher icon is the visual representation of your app on the Home or All Apps screen. Since the -user can change the Home screen's wallpaper, make sure that your launcher icon is clearly visible on -any type of background.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_launcher_size.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_launcher_focal.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_launcher_style.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <h4>Sizes & scale</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Launcher icons on a mobile device must be <strong>48x48 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> - <li class="no-bullet with-icon web"> - <p>Launcher icons for display in Market must be <strong>512x512 pixels</strong>.</p></li> - </ul> - - </div> - <div class="layout-content-col span-4"> - - <h4>Proportions</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Full asset, <strong>48x48 dp</strong></p> - </li> - </ul> - - </div> - <div class="layout-content-col span-4"> - -<h4>Style</h4> -<p>Use a distinct silhouette. Three-dimensional, front view, with a slight perspective as if viewed -from above, so that users perceive some depth.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/iconography_launcher_example.png"> - - </div> - <!-- 2 free columns --> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-12"> - - <img src="../static/content/iconography_launcher_example2.png"> - - <div class="vspace size-2"> </div> - - </div> - <!-- 1 free columns --> -</div> - - -<h2 id="actionbar">Action Bar</h2> - -<p> - -Action bar icons are graphic buttons that represent the most important actions people can take -within your app. Each one should employ a simple metaphor representing a single concept that most -people can grasp at a glance. - -</p> -<p> - -Pre-defined glyphs should be used for certain common actions such as "refresh" and "share." The -download link below provides a package with icons that are scaled for various screen densities and -are suitable for use with the Holo Light and Holo Dark themes. The package also includes unstyled -icons that you can modify to match your theme, in addition to Adobe® Illustrator® source -files for further customization. - -</p> -<p> - -<a href="../static/download/action_bar_icons-v4.0.zip">Download the Action Bar Icon -Pack</a> - -</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_actionbar_size.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_actionbar_focal.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_actionbar_style.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <h4>Sizes & scale</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Action bar icons for phones should be <strong>32x32 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> - </ul> - - </div> - <div class="layout-content-col span-4"> - - <h4>Focal area & proportions</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Full asset, <strong>32x32 dp</strong></p> - <p>Optical square, <strong>24x24 dp</strong></p> - </li> - </ul> - - </div> - <div class="layout-content-col span-4"> - -<h4>Style</h4> -<p>Pictographic, flat, not too detailed, with smooth curves or sharp shapes. If the graphic is thin, -rotate it 45° left or right to fill the focal space. The thickness of the strokes and negative -spaces should be a minimum of 2 dp.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-3"> - -<h4>Colors</h4> -<p>Colors: <strong>#333333</strong><br /> -Enabled: <strong>60%</strong> opacity<br /> -Disabled: <strong>30%</strong> opacity</p> -<div class="vspace size-1"> </div> - -<p>Colors: <strong>#FFFFFF</strong><br /> -Enabled: <strong>80%</strong> opacity<br /> -Disabled: <strong>30%</strong> opacity</p> - - </div> - <div class="layout-content-col span-9"> - - <img src="../static/content/iconography_actionbar_colors.png"> - - </div> -</div> - - -<h2 id="small_contextual">Small / Contextual Icons</h2> - -<p>Within the body of your app, use small icons to surface actions and/or provide status for specific -items. For example, in the Gmail app, each message has a star icon that marks the message as -important.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_small_size.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_small_focal.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_small_style.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <h4>Sizes & scale</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Small icons should be <strong>16x16 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> - </ul> - - </div> - <div class="layout-content-col span-4"> - - <h4>Focal area & proportions</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Full asset, <strong>16x16 dp</strong></p> - <p>Optical square, <strong>12x12 dp</strong></p> - </li> - </ul> - - </div> - <div class="layout-content-col span-4"> - -<h4>Style</h4> -<p>Neutral, flat, and simple. Filled shapes are easier to see than thin strokes. Use a single visual -metaphor so that a user can easily recognize and understand its purpose.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_small_colors.png"> - - <div class="vspace size-2"> </div> - -<h4>Colors</h4> -<p>Use non-neutral colors sparingly and with purpose. For example, Gmail uses yellow in the star icon -to indicate a bookmarked message. If an icon is actionable, choose a color that contrasts well with -the background.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/iconography_small_example.png"> - - </div> - <!-- 2 free columns --> -</div> - - -<h2 id="notification">Notification Icons</h2> - -<p>If your app generates notifications, provide an icon that the system can display in the status bar -whenever a new notification is available.</p> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_notification_size.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_notification_focal.png"> - - </div> - <div class="layout-content-col span-4"> - - <img src="../static/content/iconography_notification_style.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - - <h4>Sizes & scale</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Notification icons must be <strong>24x24 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> - </ul> - - </div> - <div class="layout-content-col span-4"> - - <h4>Focal area & proportions</h4> - - <ul> - <li class="no-bullet with-icon tablet"> - <p>Full asset, <strong>24x24 dp</strong></p> - <p>Optical square, <strong>22x22 dp</strong></p> - </li> - </ul> - - </div> - <div class="layout-content-col span-4"> - -<h4>Style</h4> -<p>Keep the style flat and simple, using the same single, visual metaphor as your launcher icon.</p> - - </div> -</div> - - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - -<h4>Colors</h4> -<p>Notification icons must be entirely white. Also, the system may scale down and/or darken the icons.</p> - - </div> - <div class="layout-content-col span-7"> - - <img src="../static/content/iconography_notification_example.png"> - - </div> - <!-- 2 free columns --> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/iconography.jd b/docs/html/design/style/iconography.jd new file mode 100644 index 0000000..775e45d --- /dev/null +++ b/docs/html/design/style/iconography.jd @@ -0,0 +1,340 @@ +page.title=Iconography +@jd:body + +<img src="{@docRoot}design/media/iconography_overview.png"> + +<p>An icon is a graphic that takes up a small portion of screen real estate and provides a quick, +intuitive representation of an action, a status, or an app.</p> + + + +<h2 id="launcher">Launcher</h2> + +<p>The launcher icon is the visual representation of your app on the Home or All Apps screen. Since the +user can change the Home screen's wallpaper, make sure that your launcher icon is clearly visible on +any type of background.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_launcher_size.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_launcher_focal.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_launcher_style.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <h4>Sizes & scale</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Launcher icons on a mobile device must be <strong>48x48 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> + <li class="no-bullet with-icon web"> + <p>Launcher icons for display on Google Play must be <strong>512x512 pixels</strong>.</p></li> + </ul> + + </div> + <div class="layout-content-col span-4"> + + <h4>Proportions</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Full asset, <strong>48x48 dp</strong></p> + </li> + </ul> + + </div> + <div class="layout-content-col span-4"> + +<h4>Style</h4> +<p>Use a distinct silhouette. Three-dimensional, front view, with a slight perspective as if viewed +from above, so that users perceive some depth.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/iconography_launcher_example.png"> + + </div> + <!-- 2 free columns --> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-12"> + + <img src="{@docRoot}design/media/iconography_launcher_example2.png"> + + <div class="vspace size-2"> </div> + + </div> + <!-- 1 free columns --> +</div> + + +<h2 id="action-bar">Action Bar</h2> + +<p> + +Action bar icons are graphic buttons that represent the most important actions people can take +within your app. Each one should employ a simple metaphor representing a single concept that most +people can grasp at a glance. + +</p> +<p> + +Pre-defined glyphs should be used for certain common actions such as "refresh" and "share." The +download link below provides a package with icons that are scaled for various screen densities and +are suitable for use with the Holo Light and Holo Dark themes. The package also includes unstyled +icons that you can modify to match your theme, in addition to Adobe® Illustrator® source +files for further customization. + +</p> +<p> + +<a href="https://dl-ssl.google.com/android/design/Android_Design_Icons_20120229.zip">Download the Action Bar Icon Pack</a> + +</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_actionbar_size.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_actionbar_focal.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_actionbar_style.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <h4>Sizes & scale</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Action bar icons for phones should be <strong>32x32 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> + </ul> + + </div> + <div class="layout-content-col span-4"> + + <h4>Focal area & proportions</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Full asset, <strong>32x32 dp</strong></p> + <p>Optical square, <strong>24x24 dp</strong></p> + </li> + </ul> + + </div> + <div class="layout-content-col span-4"> + +<h4>Style</h4> +<p>Pictographic, flat, not too detailed, with smooth curves or sharp shapes. If the graphic is thin, +rotate it 45° left or right to fill the focal space. The thickness of the strokes and negative +spaces should be a minimum of 2 dp.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-3"> + +<h4>Colors</h4> +<p>Colors: <strong>#333333</strong><br /> +Enabled: <strong>60%</strong> opacity<br /> +Disabled: <strong>30%</strong> opacity</p> +<div class="vspace size-1"> </div> + +<p>Colors: <strong>#FFFFFF</strong><br /> +Enabled: <strong>80%</strong> opacity<br /> +Disabled: <strong>30%</strong> opacity</p> + + </div> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/iconography_actionbar_colors.png"> + + </div> +</div> + + +<h2 id="small-contextual">Small / Contextual Icons</h2> + +<p>Within the body of your app, use small icons to surface actions and/or provide status for specific +items. For example, in the Gmail app, each message has a star icon that marks the message as +important.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_small_size.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_small_focal.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_small_style.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <h4>Sizes & scale</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Small icons should be <strong>16x16 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> + </ul> + + </div> + <div class="layout-content-col span-4"> + + <h4>Focal area & proportions</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Full asset, <strong>16x16 dp</strong></p> + <p>Optical square, <strong>12x12 dp</strong></p> + </li> + </ul> + + </div> + <div class="layout-content-col span-4"> + +<h4>Style</h4> +<p>Neutral, flat, and simple. Filled shapes are easier to see than thin strokes. Use a single visual +metaphor so that a user can easily recognize and understand its purpose.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_small_colors.png"> + + <div class="vspace size-2"> </div> + +<h4>Colors</h4> +<p>Use non-neutral colors sparingly and with purpose. For example, Gmail uses yellow in the star icon +to indicate a bookmarked message. If an icon is actionable, choose a color that contrasts well with +the background.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/iconography_small_example.png"> + + </div> + <!-- 2 free columns --> +</div> + + +<h2 id="notification">Notification Icons</h2> + +<p>If your app generates notifications, provide an icon that the system can display in the status bar +whenever a new notification is available.</p> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_notification_size.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_notification_focal.png"> + + </div> + <div class="layout-content-col span-4"> + + <img src="{@docRoot}design/media/iconography_notification_style.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + + <h4>Sizes & scale</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Notification icons must be <strong>24x24 <acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi screen.">dp</acronym></strong>.</p></li> + </ul> + + </div> + <div class="layout-content-col span-4"> + + <h4>Focal area & proportions</h4> + + <ul> + <li class="no-bullet with-icon tablet"> + <p>Full asset, <strong>24x24 dp</strong></p> + <p>Optical square, <strong>22x22 dp</strong></p> + </li> + </ul> + + </div> + <div class="layout-content-col span-4"> + +<h4>Style</h4> +<p>Keep the style flat and simple, using the same single, visual metaphor as your launcher icon.</p> + + </div> +</div> + + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + +<h4>Colors</h4> +<p>Notification icons must be entirely white. Also, the system may scale down and/or darken the icons.</p> + + </div> + <div class="layout-content-col span-7"> + + <img src="{@docRoot}design/media/iconography_notification_example.png"> + + </div> + <!-- 2 free columns --> +</div> diff --git a/docs/html/design/style/index.html b/docs/html/design/style/index.html deleted file mode 100644 index 5ecbafa..0000000 --- a/docs/html/design/style/index.html +++ /dev/null @@ -1,171 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Design Elements - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - -<style> -#landing-graphic-container { - position: relative; -} - -#text-overlay { - position: absolute; - left: 10px; - top: 402px; - width: 220px; -} -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - -<div class="layout-content-row content-header just-links"> - <div class="layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> -</div> - - - - -<div id="landing-graphic-container"> - <div id="text-overlay"> - Build visually compelling apps that look great on any device. - <br><br> - <a href="../style/devices-displays.html" class="landing-page-link">Devices and Displays</a> - </div> - - <a href="../style/devices-displays.html"> - <img src="../static/content/design_elements_landing.png"> - </a> -</div> - - - - - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/index.jd b/docs/html/design/style/index.jd new file mode 100644 index 0000000..d346aea --- /dev/null +++ b/docs/html/design/style/index.jd @@ -0,0 +1,29 @@ +page.title=Style +header.justLinks=1 +footer.hide=1 +@jd:body + +<style> +#landing-graphic-container { + position: relative; +} + +#text-overlay { + position: absolute; + left: 10px; + top: 402px; + width: 220px; +} +</style> + +<div id="landing-graphic-container"> + <div id="text-overlay"> + Build visually compelling apps that look great on any device. + <br><br> + <a href="{@docRoot}design/style/devices-displays.html" class="landing-page-link">Devices and Displays</a> + </div> + + <a href="{@docRoot}design/style/devices-displays.html"> + <img src="{@docRoot}design/media/design_elements_landing.png"> + </a> +</div> diff --git a/docs/html/design/style/metrics-grids.html b/docs/html/design/style/metrics-grids.html deleted file mode 100644 index 17d4937..0000000 --- a/docs/html/design/style/metrics-grids.html +++ /dev/null @@ -1,214 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Metrics and Grids - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Metrics and Grids</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>Devices vary not only in physical size, but also in screen density (<acronym title="Dots per -inch">DPI</acronym>). To simplify the way you design for multiple screens, think of each device as -falling into a particular size bucket and density bucket. The size buckets are <em>handset</em> (smaller than -600<acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi -screen.">dp</acronym>) and <em>tablet</em> (larger than or equal 600dp). The density buckets are <acronym -title="Low density (120 dpi)">LDPI</acronym>, <acronym title="Medium density (160 -dpi)">MDPI</acronym>, <acronym title="High density (240 dpi)">HDPI</acronym>, and <acronym title -="Extra-high density (320 dpi)">XHDPI</acronym>. Optimize your application's UI by designing -alternative layouts for some of the different size buckets, and provide alternative bitmap images -for different density buckets.</p> - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/metrics_diagram.png"> - - </div> - <div class="layout-content-col span-5"> - -<h4>Space considerations</h4> -<p>Devices vary in the amount of density-independent pixels (dp) they can display.</p> -<p>To see more, visit the -<a href="http://developer.android.com/resources/dashboard/screens.html" target="_blank"> -Screen Sizes and Densities Device Dashboard</a>.</p> - - </div> -</div> - -<h2>48dp Rhythm</h2> - -<p>Touchable UI components are generally laid out along 48dp units.</p> - -<img src="../static/content/metrics_48.png"> - -<div class="vspace size-2"> </div> - -<h4>Why 48dp?</h4> -<p>On average, 48dp translate to a physical size of about 9mm (with some variability). This is -comfortably in the range of recommended target sizes (7-10 mm) for touchscreen objects and users -will be able to reliably and accurately target them with their fingers.</p> -<p>If you design your elements to be at least 48dp high and wide you can guarantee that:</p> -<ul> -<li>your targets will never be smaller than the minimum recommended target size of 7mm regardless of - what screen they are displayed on.</li> -<li>you strike a good compromise between overall information density on the one hand, and - targetability of UI elements on the other.</li> -</ul> - -<img src="../static/content/metrics_closeup.png"> - -<div class="vspace size-2"> </div> - -<h4>Mind the gaps</h4> -<p>Spacing between each UI element is 8dp.</p> - -<h2>Examples</h2> - -<img src="../static/content/metrics_forms.png"> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/metrics-grids.jd b/docs/html/design/style/metrics-grids.jd new file mode 100644 index 0000000..e2b9ab5 --- /dev/null +++ b/docs/html/design/style/metrics-grids.jd @@ -0,0 +1,61 @@ +page.title=Metrics and Grids +@jd:body + +<p>Devices vary not only in physical size, but also in screen density (<acronym title="Dots per +inch">DPI</acronym>). To simplify the way you design for multiple screens, think of each device as +falling into a particular size bucket and density bucket. The size buckets are <em>handset</em> (smaller than +600<acronym title="Density-independent pixels. One dp is one pixel on a 160 dpi +screen.">dp</acronym>) and <em>tablet</em> (larger than or equal 600dp). The density buckets are <acronym +title="Low density (120 dpi)">LDPI</acronym>, <acronym title="Medium density (160 +dpi)">MDPI</acronym>, <acronym title="High density (240 dpi)">HDPI</acronym>, and <acronym title +="Extra-high density (320 dpi)">XHDPI</acronym>. Optimize your application's UI by designing +alternative layouts for some of the different size buckets, and provide alternative bitmap images +for different density buckets.</p> + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/metrics_diagram.png"> + + </div> + <div class="layout-content-col span-5"> + +<h4>Space considerations</h4> +<p>Devices vary in the amount of density-independent pixels (dp) they can display.</p> +<p>To see more, visit the +<a href="http://developer.android.com/resources/dashboard/screens.html" target="_blank"> +Screen Sizes and Densities Device Dashboard</a>.</p> + + </div> +</div> + +<h2 id="48dp-rhythm">48dp Rhythm</h2> + +<p>Touchable UI components are generally laid out along 48dp units.</p> + +<img src="{@docRoot}design/media/metrics_48.png"> + +<div class="vspace size-2"> </div> + +<h4>Why 48dp?</h4> +<p>On average, 48dp translate to a physical size of about 9mm (with some variability). This is +comfortably in the range of recommended target sizes (7-10 mm) for touchscreen objects and users +will be able to reliably and accurately target them with their fingers.</p> +<p>If you design your elements to be at least 48dp high and wide you can guarantee that:</p> +<ul> +<li>your targets will never be smaller than the minimum recommended target size of 7mm regardless of + what screen they are displayed on.</li> +<li>you strike a good compromise between overall information density on the one hand, and + targetability of UI elements on the other.</li> +</ul> + +<img src="{@docRoot}design/media/metrics_closeup.png"> + +<div class="vspace size-2"> </div> + +<h4>Mind the gaps</h4> +<p>Spacing between each UI element is 8dp.</p> + +<h2 id="examples">Examples</h2> + +<img src="{@docRoot}design/media/metrics_forms.png"> diff --git a/docs/html/design/style/themes.html b/docs/html/design/style/themes.html deleted file mode 100644 index ada974d..0000000 --- a/docs/html/design/style/themes.html +++ /dev/null @@ -1,195 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Themes - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Themes</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<div class="layout-content-row"> - <div class="layout-content-col span-5"> - - <img src="../static/content/themes_holo_light.png"> - <div class="figure-caption"> - Gmail in Holo Light. - </div> - - <img src="../static/content/themes_holo_dark.png"> - <div class="figure-caption"> - Settings in Holo Dark. - </div> - - <img src="../static/content/themes_holo_inverse.png"> - <div class="figure-caption"> - Talk in Holo Light with dark action bar. - </div> - - </div> - <div class="layout-content-col span-7"> - -<p>Themes are Android's mechanism for applying a consistent style to an app or activity. The style -specifies the visual properties of the elements that make up your user interface, such as color, -height, padding and font size. To promote greater cohesion between all apps on the platform, Android -provides three system themes that you can choose from when building apps for Ice Cream Sandwich:</p> -<ul> -<li>Holo Light</li> -<li>Holo Dark</li> -<li>Holo Light with dark action bars</li> -</ul> -<p>Applying these themes will go a long way in helping you to build apps that fit right into the -general visual language of Android.</p> -<p>Pick the system theme that best matches the needs and design aesthetics for your app. If your -desire is to have a more distinct look for your app, using one of the system themes as a starting -point for your customizations is a good idea. The system themes provide a solid foundation on top -of which you can selectively implement your own visual stylings.</p> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/themes.jd b/docs/html/design/style/themes.jd new file mode 100644 index 0000000..d4a6acf --- /dev/null +++ b/docs/html/design/style/themes.jd @@ -0,0 +1,42 @@ +page.title=Themes +@jd:body + +<div class="layout-content-row"> + <div class="layout-content-col span-5"> + + <img src="{@docRoot}design/media/themes_holo_light.png"> + <div class="figure-caption"> + Gmail in Holo Light. + </div> + + <img src="{@docRoot}design/media/themes_holo_dark.png"> + <div class="figure-caption"> + Settings in Holo Dark. + </div> + + <img src="{@docRoot}design/media/themes_holo_inverse.png"> + <div class="figure-caption"> + Talk in Holo Light with dark action bar. + </div> + + </div> + <div class="layout-content-col span-7"> + +<p>Themes are Android's mechanism for applying a consistent style to an app or activity. The style +specifies the visual properties of the elements that make up your user interface, such as color, +height, padding and font size. To promote greater cohesion between all apps on the platform, Android +provides three system themes that you can choose from when building apps for Ice Cream Sandwich:</p> +<ul> +<li>Holo Light</li> +<li>Holo Dark</li> +<li>Holo Light with dark action bars</li> +</ul> +<p>Applying these themes will go a long way in helping you to build apps that fit right into the +general visual language of Android.</p> +<p>Pick the system theme that best matches the needs and design aesthetics for your app. If your +desire is to have a more distinct look for your app, using one of the system themes as a starting +point for your customizations is a good idea. The system themes provide a solid foundation on top +of which you can selectively implement your own visual stylings.</p> + + </div> +</div> diff --git a/docs/html/design/style/touch-feedback.html b/docs/html/design/style/touch-feedback.html deleted file mode 100644 index 0d49832..0000000 --- a/docs/html/design/style/touch-feedback.html +++ /dev/null @@ -1,220 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Touch Feedback - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Touch Feedback</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<div class="layout-content-row" style="margin-bottom: -100px"> - <div class="layout-content-col span-7"> - -<p>Use color and illumination to respond to touches, reinforce the resulting behaviors of gestures, and -indicate what actions are enabled and disabled.</p> -<p>Whenever a user touches an actionable area in your app, provide a visual response. This lets the -user know which object was touched and that your app is "listening".</p> - - </div> - <div class="layout-content-col span-6"> - - <img src="../static/content/touch_feedback_reaction_response.png"> - - </div> -</div> - -<h4>States</h4> - -<div class="vspace size-1"> </div> - -<img src="../static/content/touch_feedback_states.png"> -<div class="figure-caption"> - Most of Android's UI elements have touch-feedback built in, including states that indicate - whether touching the element will have any effect. -</div> - -<div class="vspace size-4"> </div> - -<div class="layout-content-row"> - <div class="layout-content-col span-4"> - -<h4>Communication</h4> -<p>When your objects react to more complex gestures, help users understand what the outcome of the -operation will be. For example, in Recents, when you start swiping a thumbnail left or right, it -starts to dim. This helps the user understand that swiping will cause the item to be removed.</p> - - </div> - <div class="layout-content-col span-9"> - - <img src="../static/content/touch_feedback_manipulation.png"> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - - <img src="../static/content/touch_feedback_communication.png"> - - </div> - <div class="layout-content-col span-6"> - -<div class="vspace size-3"> </div> - -<h4>Boundaries</h4> -<p>When users try to scroll past the upper or lower limit of a scrollable area, communicate the -boundary with a visual cue. For example, if a user attempts to scroll past the first home screen -panel, the screen content tilts to the right to indicate that further navigation in this direction -is not possible. Many of Android's scrollable UI widgets (e.g. lists or grid lists) already have -support for boundary feedback built in. If you are building custom, keep boundary feedback in mind -and provide it from within your app.</p> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/touch-feedback.jd b/docs/html/design/style/touch-feedback.jd new file mode 100644 index 0000000..5fe72a7 --- /dev/null +++ b/docs/html/design/style/touch-feedback.jd @@ -0,0 +1,67 @@ +page.title=Touch Feedback +@jd:body + +<div class="layout-content-row" style="margin-bottom: -100px"> + <div class="layout-content-col span-7"> + +<p>Use color and illumination to respond to touches, reinforce the resulting behaviors of gestures, and +indicate what actions are enabled and disabled.</p> +<p>Whenever a user touches an actionable area in your app, provide a visual response. This lets the +user know which object was touched and that your app is "listening".</p> + + </div> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/touch_feedback_reaction_response.png"> + + </div> +</div> + +<h4>States</h4> + +<div class="vspace size-1"> </div> + +<img src="{@docRoot}design/media/touch_feedback_states.png"> +<div class="figure-caption"> + Most of Android's UI elements have touch-feedback built in, including states that indicate + whether touching the element will have any effect. +</div> + +<div class="vspace size-4"> </div> + +<div class="layout-content-row"> + <div class="layout-content-col span-4"> + +<h4>Communication</h4> +<p>When your objects react to more complex gestures, help users understand what the outcome of the +operation will be. For example, in Recents, when you start swiping a thumbnail left or right, it +starts to dim. This helps the user understand that swiping will cause the item to be removed.</p> + + </div> + <div class="layout-content-col span-9"> + + <img src="{@docRoot}design/media/touch_feedback_manipulation.png"> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + + <img src="{@docRoot}design/media/touch_feedback_communication.png"> + + </div> + <div class="layout-content-col span-6"> + +<div class="vspace size-3"> </div> + +<h4>Boundaries</h4> +<p>When users try to scroll past the upper or lower limit of a scrollable area, communicate the +boundary with a visual cue. For example, if a user attempts to scroll past the first home screen +panel, the screen content tilts to the right to indicate that further navigation in this direction +is not possible. Many of Android's scrollable UI widgets (e.g. lists or grid lists) already have +support for boundary feedback built in. If you are building custom, keep boundary feedback in mind +and provide it from within your app.</p> + + </div> +</div> diff --git a/docs/html/design/style/typography.html b/docs/html/design/style/typography.html deleted file mode 100644 index d3cc769..0000000 --- a/docs/html/design/style/typography.html +++ /dev/null @@ -1,210 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Typography - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Typography</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<div class="layout-content-row"> - <div class="layout-content-col span-8"> - - <img src="../static/content/typography_main.png"> - - </div> - <div class="layout-content-col span-5"> - -<p>The Android design language relies on traditional typographic tools such as scale, space, rhythm, -and alignment with an underlying grid. Successful deployment of these tools is essential to help -users quickly understand a screen of information. To support such use of typography, Ice Cream -Sandwich introduced a new type family named Roboto, created specifically for the requirements of UI -and high-resolution screens. The current TextView framework supports regular, bold, italic, and bold -italic weights by default.</p> - - <img src="../static/content/typography_alphas.png"> - -<p><a href="../static/download/Roboto_Hinted_20111129.zip">Download Roboto</a></p> -<p><a href="../static/download/RobotoSpecimenBook.pdf">Specimen Book</a></p> - - </div> -</div> - -<hr> - -<div class="layout-content-row"> - <div class="layout-content-col span-6"> - -<h4>Default type colors</h4> -<p>The Android UI uses the following default color styles: <code>textColorPrimary</code> and -<code>textColorSecondary</code>. For light themes use <code>textColorPrimaryInverse</code> and -<code>textColorSecondaryInverse</code>. The framework text color styles also support variants for -touch feedback states when used inside UI elements.</p> - - <img src="../static/content/typography_defaults.png"> - - </div> - <div class="layout-content-col span-6"> - -<h4>Typographic Scale</h4> -<p>Contrast in type sizes can go a long way to create ordered, understandable layouts. However, too -many different sizes in the same UI can be messy. The Android framework uses the following limited -set of type sizes:</p> - -<img src="../static/content/typography_sizes.png"> - -<p>Users can select a system-wide scaling factor for text in the Settings app. In order to support -these accessibility features, type should be specified in scale-independent pixels -(<acronym title="Scale-independent pixels. One sp is one pixel on a 160 dpi screen if the user's global text scale is set to 100%.">sp</acronym>) -wherever possible. Layouts supporting scalable types should be tested against these settings.</p> - - </div> -</div> - - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/typography.jd b/docs/html/design/style/typography.jd new file mode 100644 index 0000000..db2fb5f --- /dev/null +++ b/docs/html/design/style/typography.jd @@ -0,0 +1,56 @@ +page.title=Typography +@jd:body + +<div class="layout-content-row"> + <div class="layout-content-col span-8"> + + <img src="{@docRoot}design/media/typography_main.png"> + + </div> + <div class="layout-content-col span-5"> + +<p>The Android design language relies on traditional typographic tools such as scale, space, rhythm, +and alignment with an underlying grid. Successful deployment of these tools is essential to help +users quickly understand a screen of information. To support such use of typography, Ice Cream +Sandwich introduced a new type family named Roboto, created specifically for the requirements of UI +and high-resolution screens. The current TextView framework supports regular, bold, italic, and bold +italic weights by default.</p> + + <img src="{@docRoot}design/media/typography_alphas.png"> + +<p><a href="https://dl-ssl.google.com/android/design/Roboto_Hinted_20111129.zip">Download Roboto</a></p> +<p><a href="https://dl-ssl.google.com/android/design/Roboto_Specimen_Book_20111129.pdf">Specimen Book</a></p> + + </div> +</div> + +<hr> + +<div class="layout-content-row"> + <div class="layout-content-col span-6"> + +<h4>Default type colors</h4> +<p>The Android UI uses the following default color styles: <code>textColorPrimary</code> and +<code>textColorSecondary</code>. For light themes use <code>textColorPrimaryInverse</code> and +<code>textColorSecondaryInverse</code>. The framework text color styles also support variants for +touch feedback states when used inside UI elements.</p> + + <img src="{@docRoot}design/media/typography_defaults.png"> + + </div> + <div class="layout-content-col span-6"> + +<h4>Typographic Scale</h4> +<p>Contrast in type sizes can go a long way to create ordered, understandable layouts. However, too +many different sizes in the same UI can be messy. The Android framework uses the following limited +set of type sizes:</p> + +<img src="{@docRoot}design/media/typography_sizes.png"> + +<p>Users can select a system-wide scaling factor for text in the Settings app. In order to support +these accessibility features, type should be specified in scale-independent pixels +(<acronym title="Scale-independent pixels. One sp is one pixel on a 160 dpi screen if the user's global text scale is set to 100%.">sp</acronym>) +wherever possible. Layouts supporting scalable types should be tested against these settings.</p> + + </div> +</div> diff --git a/docs/html/design/style/writing.html b/docs/html/design/style/writing.html deleted file mode 100644 index e5f1ea8..0000000 --- a/docs/html/design/style/writing.html +++ /dev/null @@ -1,483 +0,0 @@ -<!DOCTYPE html> -<html lang="en"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title> - -Android Design - Writing Style - </title> - <link rel="shortcut icon" type="image/x-icon" href="/favicon.ico"> - <link rel="stylesheet" href="http://fonts.googleapis.com/css?family=Roboto:regular,medium,thin,italic,mediumitalic"> - <link rel="stylesheet" href="../static/yui-3.3.0-reset-min.css"> - <link rel="stylesheet" href="../static/default.css"> - -<style> - -/* UI tables */ - -.ui_table { - width: 100%; - background: #282828; - color: #fff; - border-radius: 2px; - box-shadow: 0 2px 4px rgba(0,0,0,0.25); - border-collapse: separate; -} - -.ui_table th, -.ui_table td { - padding: 5px 10px; -} - -.ui_table thead th { - font-weight: 600; -} - -.ui_table tfoot td { - border-top: 1px solid #494949; - border-right: 1px solid #494949; - text-align: center; -} - -.ui_table tfoot td:last-child { - border-right: 0; -} - -.list_item_margins { - margin-left: 30px !important; -} - -.example_label { - margin-bottom: 10px; - padding-left: 20px; - background: transparent none no-repeat scroll 0px 3px; -} - -.example_label.bad { - background-image: url(../static/ico_wrong.png); -} - -.example_label.good { - background-image: url(../static/ico_good.png); -} - -</style> - - </head> - <body> - - <div id="page-container"> - - <div id="page-header"><a href="../index.html">Android Design</a></div> - - <div id="main-row"> - - <ul id="nav"> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../index.html">Get Started</a></div> - <ul> - <li><a href="../get-started/creative-vision.html">Creative Vision</a></li> - <li><a href="../get-started/principles.html">Design Principles</a></li> - <li><a href="../get-started/ui-overview.html">UI Overview</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../style/index.html">Style</a></div> - <ul> - <li><a href="../style/devices-displays.html">Devices and Displays</a></li> - <li><a href="../style/themes.html">Themes</a></li> - <li><a href="../style/touch-feedback.html">Touch Feedback</a></li> - <li><a href="../style/metrics-grids.html">Metrics and Grids</a></li> - <li><a href="../style/typography.html">Typography</a></li> - <li><a href="../style/color.html">Color</a></li> - <li><a href="../style/iconography.html">Iconography</a></li> - <li><a href="../style/writing.html">Writing Style</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../patterns/index.html">Patterns</a></div> - <ul> - <li><a href="../patterns/new-4-0.html">New in Android 4.0</a></li> - <li><a href="../patterns/gestures.html">Gestures</a></li> - <li><a href="../patterns/app-structure.html">App Structure</a></li> - <li><a href="../patterns/navigation.html">Navigation</a></li> - <li><a href="../patterns/actionbar.html">Action Bar</a></li> - <li><a href="../patterns/multi-pane-layouts.html">Multi-pane Layouts</a></li> - <li><a href="../patterns/swipe-views.html">Swipe Views</a></li> - <li><a href="../patterns/selection.html">Selection</a></li> - <li><a href="../patterns/notifications.html">Notifications</a></li> - <li><a href="../patterns/compatibility.html">Compatibility</a></li> - <li><a href="../patterns/pure-android.html">Pure Android</a></li> - </ul> - </li> - - <li class="nav-section"> - <div class="nav-section-header"><a href="../building-blocks/index.html">Building Blocks</a></div> - <ul> - <li><a href="../building-blocks/tabs.html">Tabs</a></li> - <li><a href="../building-blocks/lists.html">Lists</a></li> - <li><a href="../building-blocks/grid-lists.html">Grid Lists</a></li> - <li><a href="../building-blocks/scrolling.html">Scrolling</a></li> - <li><a href="../building-blocks/spinners.html">Spinners</a></li> - <li><a href="../building-blocks/buttons.html">Buttons</a></li> - <li><a href="../building-blocks/text-fields.html">Text Fields</a></li> - <li><a href="../building-blocks/seek-bars.html">Seek Bars</a></li> - <li><a href="../building-blocks/progress.html">Progress & Activity</a></li> - <li><a href="../building-blocks/switches.html">Switches</a></li> - <li><a href="../building-blocks/dialogs.html">Dialogs</a></li> - <li><a href="../building-blocks/pickers.html">Pickers</a></li> - </ul> - </li> - - <li> - <div id="back-dac-section"><a href="../../index.html">Developers</a></div> - </li> - - </ul> - - <div id="content"> - - - <div class="layout-content-row content-header"> - <div class="layout-content-col span-9"> - <h2>Writing Style</h2> - </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - - - -<p>When choosing words for your app:</p> -<ol> -<li> -<p><strong>Keep it brief.</strong> Be concise, simple and precise. Start with a 30 character limit (including - spaces), and don't use more unless absolutely necessary.</p> -</li> -<li> -<p><strong>Keep it simple.</strong> Pretend you're speaking to someone who's smart and competent, but doesn't - know technical jargon and may not speak English very well. Use short words, active verbs, and - common nouns.</p> -</li> -<li> -<p><strong>Be friendly.</strong> Use contractions. Talk directly to the reader using second person ("you"). If - your text doesn't read the way you'd say it in casual conversation, it's probably not the way - you should write it. Don't be abrupt or annoying and make the user feel safe, happy and - energized.</p> -</li> -<li> -<p><strong>Put the most important thing first.</strong> The first two words (around 11 characters, including - spaces) should include at least a taste of the most important information in the string. If they - don't, start over.</p> -</li> -<li> -<p><strong>Describe only what's necessary, and no more.</strong> Don't try to explain subtle differences. They - will be lost on most users.</p> -</li> -<li> -<p><strong>Avoid repetition.</strong> If a significant term gets repeated within a screen or block of text, find - a way to use it just once.</p> -</li> -</ol> - -<h2>Examples</h2> - -<ol><li class="value-1"><strong>Keep it brief.</strong> From the setup wizard:</ol> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">Too formal</div> - - <table class="ui_table good"><tbody><tr><td> - Consult the documentation that came with your phone for further instructions. - </td></tr></tbody></table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">Better</div> - - <table class="ui_table good"><tbody><tr><td> - Read the instructions that came with your phone. - </td></tr></tbody></table> - - </div> -</div> - -<div class="vspace size-1"> </div> - -<ol><li class="value-2"><strong>Keep it simple.</strong> From the Location settings screen:</ol> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">Confusing</div> - - <table class="ui_table bad"> - <thead> - <tr> - <th> - Use GPS satellites - </th> - </tr> - </thead> - <tbody> - <tr> - <td> - When locating, accurate to street level. - </td> - </tr> - </tbody> - </table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">Better</div> - - <table class="ui_table good"> - <thead> - <tr> - <th> - GPS - </th> - </tr> - </thead> - <tbody> - <tr> - <td> - Let apps use satellites to pinpoint your location. - </td> - </tr> - </tbody> - </table> - - </div> -</div> - -<div class="vspace size-1"> </div> - -<ol><li class="value-3"><strong>Be friendly.</strong> Dialog that appears when an application -crashes:</ol> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">Confusing and annoying—"Sorry" just rubs salt in the - wound.</div> - - <table class="ui_table bad"> - <thead> - <tr> - <th colspan="3"> - Sorry! - </th> - </tr> - </thead> - <tbody> - <tr> - <td colspan="3"> - Activity MyAppActivity (in application MyApp) - is not responding. - </td> - </tr> - </tbody> - <tfoot> - <tr> - <td width="33%">Force close</td> - <td width="33%">Wait</td> - <td width="33%">Report</td> - </tr> - </tbody> - </table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">Shorter, more direct, no faux-apologetic title:<br><br></div> - - <table class="ui_table good"> - <thead> - <tr> - <th colspan="3"> - MyApp isn't responding. - </th> - </tr> - </thead> - <tbody> - <tr> - <td colspan="3"> - Do you want to close it? - </td> - </tr> - </tbody> - <tfoot> - <tr> - <td width="33%">Wait</td> - <td width="33%">Report</td> - <td width="33%">Close</td> - </tr> - </tbody> - </table> - - </div> -</div> - -<div class="vspace size-1"> </div> - -<ol><li class="value-4"><strong>Put the most important thing first.</strong></ol> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">Top news last</div> - - <table class="ui_table bad"><tbody><tr><td> - 77 other people +1'd this, including Larry Page. - </td></tr></tbody></table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">Top news first</div> - - <table class="ui_table good"><tbody><tr><td> - Larry Page and 77 others +1'd this. - </td></tr></tbody></table> - - </div> -</div> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">Task last</div> - - <table class="ui_table bad"><tbody><tr><td> - Touch Next to complete setup using a Wi-Fi connection. - </td></tr></tbody></table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">Task first</div> - - <table class="ui_table good"><tbody><tr><td> - To finish setup using Wi-Fi, touch Next. - </td></tr></tbody></table> - - </div> -</div> - -<div class="vspace size-1"> </div> - -<ol><li class="value-5"><strong>Describe only what's necessary, and no more.</strong></ol> - -<div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> - - <div class="example_label bad">From a Setup Wizard screen</div> - - <table class="ui_table bad"> - <thead> - <tr> - <th> - Signing in... - </th> - </tr> - </thead> - <tbody> - <tr> - <td> - Your phone needs to communicate with<br> - Google servers to sign in to your account.<br> - This may take up to five minutes. - </td> - </tr> - </tbody> - </table> - - </div> - <div class="layout-content-col span-6"> - - <div class="example_label good">From a Setup Wizard screen</div> - - <table class="ui_table good"> - <thead> - <tr> - <th> - Signing in... - </th> - </tr> - </thead> - <tbody> - <tr> - <td> - Your phone is contacting Google.<br> - This can take up to 5 minutes. - </td> - </tr> - </tbody> - </table> - - </div> -</div> - - - - - <div class="layout-content-row content-footer"> - <div class="paging-links layout-content-col span-9"> </div> - <div class="paging-links layout-content-col span-4"> - <a href="#" class="prev-page-link">Previous</a> - <a href="#" class="next-page-link">Next</a> - </div> - </div> - - </div> - - </div> - - <div id="page-footer"> - - <p id="copyright"> - Except as noted, this content is licensed under - <a href="http://creativecommons.org/licenses/by/2.5/"> - Creative Commons Attribution 2.5</a>.<br> - For details and restrictions, see the - <a href="http://developer.android.com/license.html">Content License</a>. - </p> - - <p> - <a href="http://www.android.com/terms.html">Site Terms of Service</a> – - <a href="http://www.android.com/privacy.html">Privacy Policy</a> – - <a href="http://www.android.com/branding.html">Brand Guidelines</a> - </p> - - </div> - </div> - - <script src="../static/jquery-1.6.2.min.js"></script> - <script> - var SITE_ROOT = '../'; - </script> - <script src="../static/default.js"></script> - - - <script type="text/javascript"> - var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); - document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); - </script> - <script type="text/javascript"> - var pageTracker = _gat._getTracker("UA-5831155-1"); - pageTracker._trackPageview(); - </script> - </body> -</html> diff --git a/docs/html/design/style/writing.jd b/docs/html/design/style/writing.jd new file mode 100644 index 0000000..919ea7a --- /dev/null +++ b/docs/html/design/style/writing.jd @@ -0,0 +1,278 @@ +page.title=Writing Style +@jd:body + +<p>When choosing words for your app:</p> +<ol> +<li> +<p><strong>Keep it brief.</strong> Be concise, simple and precise. Start with a 30 character limit (including + spaces), and don't use more unless absolutely necessary.</p> +</li> +<li> +<p><strong>Keep it simple.</strong> Pretend you're speaking to someone who's smart and competent, but doesn't + know technical jargon and may not speak English very well. Use short words, active verbs, and + common nouns.</p> +</li> +<li> +<p><strong>Be friendly.</strong> Use contractions. Talk directly to the reader using second person ("you"). If + your text doesn't read the way you'd say it in casual conversation, it's probably not the way + you should write it. Don't be abrupt or annoying and make the user feel safe, happy and + energized.</p> +</li> +<li> +<p><strong>Put the most important thing first.</strong> The first two words (around 11 characters, including + spaces) should include at least a taste of the most important information in the string. If they + don't, start over.</p> +</li> +<li> +<p><strong>Describe only what's necessary, and no more.</strong> Don't try to explain subtle differences. They + will be lost on most users.</p> +</li> +<li> +<p><strong>Avoid repetition.</strong> If a significant term gets repeated within a screen or block of text, find + a way to use it just once.</p> +</li> +</ol> + +<h2 id="examples">Examples</h2> + +<ol><li class="value-1"><strong>Keep it brief.</strong> From the setup wizard:</ol> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">Too formal</div> + + <table class="ui-table good"><tbody><tr><td> + Consult the documentation that came with your phone for further instructions. + </td></tr></tbody></table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">Better</div> + + <table class="ui-table good"><tbody><tr><td> + Read the instructions that came with your phone. + </td></tr></tbody></table> + + </div> +</div> + +<div class="vspace size-1"> </div> + +<ol><li class="value-2"><strong>Keep it simple.</strong> From the Location settings screen:</ol> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">Confusing</div> + + <table class="ui-table bad"> + <thead> + <tr> + <th> + Use GPS satellites + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + When locating, accurate to street level. + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">Better</div> + + <table class="ui-table good"> + <thead> + <tr> + <th> + GPS + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + Let apps use satellites to pinpoint your location. + </td> + </tr> + </tbody> + </table> + + </div> +</div> + +<div class="vspace size-1"> </div> + +<ol><li class="value-3"><strong>Be friendly.</strong> Dialog that appears when an application +crashes:</ol> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">Confusing and annoying—"Sorry" just rubs salt in the + wound.</div> + + <table class="ui-table bad"> + <thead> + <tr> + <th colspan="3"> + Sorry! + </th> + </tr> + </thead> + <tbody> + <tr> + <td colspan="3"> + Activity MyAppActivity (in application MyApp) + is not responding. + </td> + </tr> + </tbody> + <tfoot> + <tr> + <td width="33%">Force close</td> + <td width="33%">Wait</td> + <td width="33%">Report</td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">Shorter, more direct, no faux-apologetic title:<br><br></div> + + <table class="ui-table good"> + <thead> + <tr> + <th colspan="3"> + MyApp isn't responding. + </th> + </tr> + </thead> + <tbody> + <tr> + <td colspan="3"> + Do you want to close it? + </td> + </tr> + </tbody> + <tfoot> + <tr> + <td width="33%">Wait</td> + <td width="33%">Report</td> + <td width="33%">Close</td> + </tr> + </tbody> + </table> + + </div> +</div> + +<div class="vspace size-1"> </div> + +<ol><li class="value-4"><strong>Put the most important thing first.</strong></ol> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">Top news last</div> + + <table class="ui-table bad"><tbody><tr><td> + 77 other people +1'd this, including Larry Page. + </td></tr></tbody></table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">Top news first</div> + + <table class="ui-table good"><tbody><tr><td> + Larry Page and 77 others +1'd this. + </td></tr></tbody></table> + + </div> +</div> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">Task last</div> + + <table class="ui-table bad"><tbody><tr><td> + Touch Next to complete setup using a Wi-Fi connection. + </td></tr></tbody></table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">Task first</div> + + <table class="ui-table good"><tbody><tr><td> + To finish setup using Wi-Fi, touch Next. + </td></tr></tbody></table> + + </div> +</div> + +<div class="vspace size-1"> </div> + +<ol><li class="value-5"><strong>Describe only what's necessary, and no more.</strong></ol> + +<div class="layout-content-row"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> + + <div class="do-dont-label bad">From a Setup Wizard screen</div> + + <table class="ui-table bad"> + <thead> + <tr> + <th> + Signing in... + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + Your phone needs to communicate with<br> + Google servers to sign in to your account.<br> + This may take up to five minutes. + </td> + </tr> + </tbody> + </table> + + </div> + <div class="layout-content-col span-6"> + + <div class="do-dont-label good">From a Setup Wizard screen</div> + + <table class="ui-table good"> + <thead> + <tr> + <th> + Signing in... + </th> + </tr> + </thead> + <tbody> + <tr> + <td> + Your phone is contacting Google.<br> + This can take up to 5 minutes. + </td> + </tr> + </tbody> + </table> + + </div> +</div> diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd index cc98f8f..bc7d83b 100644 --- a/docs/html/guide/appendix/api-levels.jd +++ b/docs/html/guide/appendix/api-levels.jd @@ -350,11 +350,11 @@ including the latest version, and provides an updater tool that you can use to download other platform versions as necessary. </p> <p>To access the updater, use the <code>android</code> command-line tool, -located in the <sdk>/tools directory. You can launch the Updater by using -the <code>android</code> command without specifying any options. You can +located in the <sdk>/tools directory. You can launch the SDK updater by +executing <code>android sdk</code>. You can also simply double-click the android.bat (Windows) or android (OS X/Linux) file. In ADT, you can also access the updater by selecting -<strong>Window</strong> > <strong>Android SDK and AVD +<strong>Window</strong> > <strong>Android SDK Manager</strong>.</p> <p>To run your application against different platform versions in the emulator, diff --git a/docs/html/guide/appendix/install-location.jd b/docs/html/guide/appendix/install-location.jd index 292d3e7..63a3817 100644 --- a/docs/html/guide/appendix/install-location.jd +++ b/docs/html/guide/appendix/install-location.jd @@ -172,9 +172,9 @@ persist after external storage is remounted.</dd> before the external storage is mounted to the device. If your application is installed on the external storage, it can never receive this broadcast.</dd> <dt>Copy Protection</dt> - <dd>Your application cannot be installed to a device's SD card if it uses Android Market's - Copy Protection feature. However, if you use Android Market's - <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, your + <dd>Your application cannot be installed to a device's SD card if it uses Google Play's + Copy Protection feature. However, if you use Google Play's + <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</dd> </dl> diff --git a/docs/html/guide/appendix/market-filters.jd b/docs/html/guide/appendix/market-filters.jd index d9b2155..3e502d7 100644 --- a/docs/html/guide/appendix/market-filters.jd +++ b/docs/html/guide/appendix/market-filters.jd @@ -1,4 +1,4 @@ -page.title=Market Filters +page.title=Filters on Google Play @jd:body <div id="qv-wrapper"> @@ -6,15 +6,15 @@ page.title=Market Filters <h2>Quickview</h2> <ul> -<li>Android Market applies filters that control which Android-powered devices can access your -application on Market.</li> +<li>Google Play applies filters that control which Android-powered devices can access your +application when the user is visiting the store.</li> <li>Filtering is determined by comparing device configurations that you declare in you app's manifest file to the configurations defined by the device, as well as other factors.</li> </ul> <h2>In this document</h2> <ol> - <li><a href="#how-filters-work">How Filters Work in Android Market</a></li> + <li><a href="#how-filters-work">How Filters Work on Google Play</a></li> <li><a href="#manifest-filters">Filtering based on Manifest Elements</a> <ol> <li><a href="#advanced-filters">Advanced manifest filters</a></li> @@ -47,10 +47,10 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></c <div id="qv-extra"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0 5px;"> - <h2 style="color:#669999;">Interested in publishing your app on Android Market?</h2> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0 5px;"> + <h2 style="color:#669999;padding-top:1em;">Interested in publishing your app on Google Play?</h2> <p><a id="publish-link" -href="http://market.android.com/publish">Go to Android Market</a> to create a publisher +href="http://play.google.com/apps/publish">Go to Google Play</a> to create a publisher account and upload your app.</p></div> </div> @@ -58,44 +58,44 @@ account and upload your app.</p></div> </div> -<p>When a user searches or browses in Android Market on an Android device, the results are filtered +<p>When a user searches or browses on Google Play on an Android device, the results are filtered based on which applications are compatible with that device. For example, if an application -requires a camera (as specified in the application manifest file), then Android Market will not show +requires a camera (as specified in the application manifest file), then Google Play will not show the app on any device that does not have a camera.</p> <p>Declarations in the manifest file that are compared to the device's configuration is not the only part of how applications are filtered. Filtering might also occur due to the user's country and carrier, the presence or absence of a SIM card, and other factors. </p> -<p>Changes to the Android Market filters are independent of changes to the Android platform itself. -This document is updated periodically to reflect any changes that affect the way Android Market +<p>Changes to the Google Play filters are independent of changes to the Android platform itself. +This document is updated periodically to reflect any changes that affect the way Google Play filters applications.</p> -<h2 id="how-filters-work">How Filters Work in Android Market</h2> +<h2 id="how-filters-work">How Filters Work on Google Play</h2> -<p>Android Market uses the filter restrictions described below to determine +<p>Google Play uses the filter restrictions described below to determine whether to show your application to a user who is browsing or searching for -applications from the Android Market app. When determining whether to display your app, -Market checks the device's hardware and software configuration, as well as it's +applications from the Google Play app. When determining whether to display your app, +Google Play checks the device's hardware and software configuration, as well as it's carrier, location, and other characteristics. It then compares those against the restrictions and dependencies expressed by the application's manifest file and publishing details. If the application is -compatible with the device according to the filter rules, Market displays the -application to the user. Otherwise, Market hides your application from search +compatible with the device according to the filter rules, Google Play displays the +application to the user. Otherwise, Google Play hides your application from search results and category browsing, even if a user specifically requests -the app by clicking a deep link that points directly to the app's ID within Market..</p> +the app by clicking a deep link that points directly to the app's ID within Google Play..</p> <p class="note"><strong>Note:</strong> When users browse the <a -href="http://market.android.com">Android Market web site</a>, they can see all published -applications. The Android Market web site compares the application requirements to each of the +href="http://play.google.com/apps">Google Play web site</a>, they can see all published +applications. The Google Play web site compares the application requirements to each of the user's registered devices for compatibility, though, and only allows them to install the application if it's compatible with their device.</p> <p>You can use any combination of the available filters for your app. For example, you can set a <code>minSdkVersion</code> requirement of <code>"4"</code> and set <code>smallScreens="false"</code> -in the app, then when uploading the app to Market you could target European countries (carriers) -only. Android Market's filters will thus prevent the application from being available on any device +in the app, then when uploading the app to Google Play you could target European countries (carriers) +only. Google Play's filters will thus prevent the application from being available on any device that does not match all three of these requirements. </p> <p>All filtering restrictions are associated with an application's version and can @@ -106,15 +106,15 @@ available.</p> <h2 id="manifest-filters">Filtering based on Manifest Elements</h2> -<p>Most Market filters are triggered by elements within an application's +<p>Most filters are triggered by elements within an application's manifest file, <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">AndroidManifest.xml</a> (although not everything in the manifest file can trigger filtering). -Table 1 lists the manifest elements that you should use to trigger Android -Market filtering, and explains how the filtering for each element works.</p> +Table 1 lists the manifest elements that you should use to trigger +filtering, and explains how the filtering for each element works.</p> <p id="table1" class="table-caption"><strong>Table 1.</strong> Manifest elements that -trigger filtering on Market.</p> +trigger filtering on Google Play.</p> <table> <tr> <th>Manifest Element</th> @@ -129,19 +129,19 @@ trigger filtering on Market.</p> <p>An application indicates the screen sizes that it is capable of supporting by setting attributes of the <code><supports-screens></code> element. When -the application is published, Market uses those attributes to determine whether +the application is published, Google Play uses those attributes to determine whether to show the application to users, based on the screen sizes of their devices. </p> -<p>As a general rule, Market assumes that the platform on the device can adapt +<p>As a general rule, Google Play assumes that the platform on the device can adapt smaller layouts to larger screens, but cannot adapt larger layouts to smaller screens. Thus, if an application declares support for "normal" screen size only, -Market makes the application available to both normal- and large-screen devices, +Google Play makes the application available to both normal- and large-screen devices, but filters the application so that it is not available to small-screen devices.</p> <p>If an application does not declare attributes for -<code><supports-screens></code>, Market uses the default values for those +<code><supports-screens></code>, Google Play uses the default values for those attributes, which vary by API Level. Specifically: </p> <ul> @@ -150,7 +150,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">android: minSdkVersion</a></code> or <code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">android: targetSdkVersion</a></code> to 3 or lower, the <code><supports-screens></code> element itself -is undefined and no attributes are available. In this case, Market assumes that +is undefined and no attributes are available. In this case, Google Play assumes that the application is designed for normal-size screens and shows the application to devices that have normal or larger screens. </p> @@ -166,19 +166,19 @@ default.</li> <p><strong>Example 1</strong><br /> The manifest declares <code><uses-sdk android:minSdkVersion="3"></code> and does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market does not show the app to a user of a - small-screen device, but does show it to users of normal and large-screen - devices, unless other filters also exclude those devices. </p> + <strong>Result</strong>: Google Play will not show the app to a user of a + small-screen device, but will show it to users of normal and large-screen + devices, unless other filters apply. </p> <p><strong>Example 2<br /> </strong>The manifest declares <code><uses-sdk android:minSdkVersion="3" android:targetSdkVersion="4"></code> and does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market will show the app to users on all + <strong>Result</strong>: Google Play will show the app to users on all devices, unless other filters apply. </p> <p><strong>Example 3<br /> </strong>The manifest declares <code><uses-sdk android:minSdkVersion="4"></code> and does not include a <code><supports-screens></code> element. - <strong>Result</strong>: Android Market will show the app to all users, + <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply. </p> <p>For more information on how to declare support for screen sizes in your application, see <code><a @@ -195,11 +195,11 @@ default.</li> Configuration: <br /> keyboard, navigation, touch screen</td> <td valign="top"><p>An application can - request certain hardware features, and Android Market will show the app only on devices that have the required hardware.</p> + request certain hardware features, and Google Play will show the app only on devices that have the required hardware.</p> <p><strong>Example 1<br /> - </strong>The manifest includes <code><uses-configuration android:reqFiveWayNav="true" /></code>, and a user is searching for apps on a device that does not have a five-way navigational control. <strong>Result</strong>: Android Market will not show the app to the user. </p> + </strong>The manifest includes <code><uses-configuration android:reqFiveWayNav="true" /></code>, and a user is searching for apps on a device that does not have a five-way navigational control. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2<br /> - </strong>The manifest does not include a <code><uses-configuration></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> + </strong>The manifest does not include a <code><uses-configuration></code> element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-configuration-element.html"><code><uses-configuration></code></a>.</p></td> </tr> @@ -218,16 +218,16 @@ Level 5).</p> </strong>The manifest includes <code><uses-feature android:name="android.hardware.sensor.light" /></code>, and a user is searching for apps on a device that does not have a light sensor. -<strong>Result</strong>: Android Market will not show the app to the user. </p> +<strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2<br /> </strong>The manifest does not include a <code><uses-feature></code> -element. <strong>Result</strong>: Android Market will show the app to all users, +element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For complete information, see <code><a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><uses-feature></a> </code>.</p> - <p><em>Filtering based on implied features:</em> In some cases, Android -Market interprets permissions requested through + <p><em>Filtering based on implied features:</em> In some cases, Google +Play interprets permissions requested through <code><uses-permission></code> elements as feature requirements equivalent to those declared in <code><uses-feature></code> elements. See <a href="#uses-permission-filtering"><code><uses-permission></code></a>, @@ -245,19 +245,19 @@ below.</p> <p><strong>Example 1<br /> </strong>An app requests multiple OpenGL-ES versions by specifying <code>openGlEsVersion</code> multiple times in the - manifest. <strong>Result</strong>: Market assumes that the app requires the highest of the indicated versions.</p> + manifest. <strong>Result</strong>: Google Play assumes that the app requires the highest of the indicated versions.</p> <p><strong>Example 2<br /> </strong>An app - requests OpenGL-ES version 1.1, and a user is searching for apps on a device that supports OpenGL-ES version 2.0. <strong>Result</strong>: Android Market will show the app to the user, unless other filters apply. If a - device reports that it supports OpenGL-ES version <em>X</em>, Market assumes that it + requests OpenGL-ES version 1.1, and a user is searching for apps on a device that supports OpenGL-ES version 2.0. <strong>Result</strong>: Google Play will show the app to the user, unless other filters apply. If a + device reports that it supports OpenGL-ES version <em>X</em>, Google Play assumes that it also supports any version earlier than <em>X</em>. </p> <p><strong>Example 3<br /> </strong>A user is searching for apps on a device that does not - report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Android Market assumes that the device - supports only OpenGL-ES 1.0. Market will only show the user apps that do not specify <code>openGlEsVersion</code>, or apps that do not specify an OpenGL-ES version higher than 1.0. </p> + report an OpenGL-ES version (for example, a device running Android 1.5 or earlier). <strong>Result</strong>: Google Play assumes that the device + supports only OpenGL-ES 1.0. Google Play will only show the user apps that do not specify <code>openGlEsVersion</code>, or apps that do not specify an OpenGL-ES version higher than 1.0. </p> <p><strong>Example 4<br /> - </strong>The manifest does not specify <code>openGlEsVersion</code>. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply. </p> + </strong>The manifest does not specify <code>openGlEsVersion</code>. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply. </p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a>.</p></td> </tr> @@ -268,28 +268,28 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses- <td valign="top"><p>An application can require specific shared libraries to be present on the device. </p> <p><strong>Example 1<br /> - </strong>An app requires the <code>com.google.android.maps</code> library, and a user is searching for apps on a device that does not have the <code>com.google.android.maps</code> library. <strong>Result</strong>: Android Market will not show the app to the user. </p> + </strong>An app requires the <code>com.google.android.maps</code> library, and a user is searching for apps on a device that does not have the <code>com.google.android.maps</code> library. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2</strong><br /> - The manifest does not include a <code><uses-library></code> element. <strong>Result</strong>: Android Market will show the app to all users, unless other filters apply.</p> + The manifest does not include a <code><uses-library></code> element. <strong>Result</strong>: Google Play will show the app to all users, unless other filters apply.</p> <p>For more details, see <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a>.</p></td> </tr> <tr id="uses-permission-filtering"> <td valign="top" style="white-space:nowrap;"><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></td> <td valign="top"> </td> - <td valign="top">Strictly, Android Market does not filter based on + <td valign="top">Strictly, Google Play does not filter based on <code><uses-permission></code> elements. However, it does read the elements to determine whether the application has hardware feature requirements that may not have been properly declared in <code><uses-feature></code> elements. For example, if an application requests the <code>CAMERA</code> permission but does not declare a <code><uses-feature></code> element for -<code>android.hardware.camera</code>, Android Market considers that the +<code>android.hardware.camera</code>, Google Play considers that the application requires a camera and should not be shown to users whose devices do not offer a camera.</p> <p>In general, if an application requests hardware-related permissions, -Android Market assumes that the application requires the underlying hardware +Google Play assumes that the application requires the underlying hardware features, even though there might be no corresponding to -<code><uses-feature></code> declarations. Android Market then sets up +<code><uses-feature></code> declarations. Google Play then sets up filtering based on the features implied by the <code><uses-feature></code> declarations.</p> <p>For a list of permissions that imply hardware features, see @@ -305,9 +305,9 @@ element.</p> <td valign="top"><p>An application can require a minimum API level. </p> <p><strong>Example 1</strong><br /> The manifest includes <code><uses-sdk - android:minSdkVersion="3"></code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market will not show the app to the user. </p> + android:minSdkVersion="3"></code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Google Play will not show the app to the user. </p> <p><strong>Example 2</strong><br /> - The manifest does not include <code>minSdkVersion</code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Android Market assumes that <code>minSdkVersion</code> is "1" and that the app is compatible with all versions of Android. Market shows the app to the user and allows the user to download the app. The app crashes at runtime. </p> + The manifest does not include <code>minSdkVersion</code>, and the app uses APIs that were introduced in API Level 3. A user is searching for apps on a device that has API Level 2. <strong>Result</strong>: Google Play assumes that <code>minSdkVersion</code> is "1" and that the app is compatible with all versions of Android. Google Play shows the app to the user and allows the user to download the app. The app crashes at runtime. </p> <p>Because you want to avoid this second scenario, we recommend that you always declare a <code>minSdkVersion</code>. For details, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:minSdkVersion</code></a>.</p></td> </tr> @@ -316,7 +316,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min"><code>android:m <td valign="top"><p><em>Deprecated.</em> Android 2.1 and later do not check or enforce the <code>maxSdkVersion</code> attribute, and the SDK will not compile if <code>maxSdkVersion</code> is set in an app's manifest. For devices already - compiled with <code>maxSdkVersion</code>, Market will respect it and use it for + compiled with <code>maxSdkVersion</code>, Google Play will respect it and use it for filtering.</p> <p> Declaring <code>maxSdkVersion</code> is <em>not</em> recommended. For details, see <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:maxSdkVersion</code></a>.</p></td> @@ -327,7 +327,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#max"><code>android:m <h3 id="advanced-filters">Advanced manifest filters</h3> -<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Android Market can also +<p>In addition to the manifest elements in <a href="#table1">table 1</a>, Google Play can also filter applications based on the advanced manifest elements in table 2.</p> <p>These manifest elements and the filtering they trigger are for exceptional use-cases @@ -336,14 +336,14 @@ require strict controls on application distribution. <strong>Most applications s these filters</strong>.</p> <p id="table2" class="table-caption"><strong>Table 2.</strong> Advanced manifest elements for -Android Market filtering.</p> +Google Play filtering.</p> <table> <tr><th>Manifest Element</th><th>Summary</th></tr> <tr> <td><nobr><a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a></nobr></td> <td> - <p>Android Market filters the application if the device screen size and density does not match + <p>Google Play filters the application if the device screen size and density does not match any of the screen configurations (declared by a {@code <screen>} element) in the {@code <compatible-screens>} element.</p> <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use @@ -360,7 +360,7 @@ with alternative resources.</p> <td><nobr><a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code <supports-gl-texture>}</a></nobr></td> <td> - <p>Android Market filters the application unless one or more of the GL texture compression + <p>Google Play filters the application unless one or more of the GL texture compression formats supported by the application are also supported by the device. </p> </td> </tr> @@ -370,16 +370,16 @@ formats supported by the application are also supported by the device. </p> <h2 id="other-filters">Other Filters</h2> -<p>Android Market uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> +<p>Google Play uses other application characteristics to determine whether to show or hide an application for a particular user on a given device, as described in the table below. </p> <p id="table3" class="table-caption"><strong>Table 3.</strong> Application and publishing -characteristics that affect filtering on Market.</p> +characteristics that affect filtering on Google Play.</p> <table> <tr> <th>Filter Name</th> <th>How It Works</th> </tr> <tr> <td valign="top">Publishing Status</td> <td valign="top"><p>Only published applications will appear in - searches and browsing within Android Market.</p> <p>Even if an app is unpublished, it can + searches and browsing within Google Play.</p> <p>Even if an app is unpublished, it can be installed if users can see it in their Downloads area among their purchased, installed, or recently uninstalled apps.</p> <p>If an application has been suspended, users will not be able to reinstall or update it, even if it appears in their Downloads.</p> </td></tr> @@ -390,10 +390,10 @@ must have a SIM card and be running Android 1.1 or later, and it must be in a country (as determined by SIM carrier) in which paid apps are available.</p></td> </tr> <tr> <td valign="top">Country / Carrier Targeting</td> <td valign="top"> <p>When you upload your app to - the Android Market, you can select specific countries to target. The app will only + Google Play, you can select specific countries to target. The app will only be visible to the countries (carriers) that you select, as follows:</p> <ul><li><p>A device's country is determined based on the carrier, if a carrier is - available. If no carrier can be determined, the Market application tries to + available. If no carrier can be determined, Google Play tries to determine the country based on IP.</p></li> <li><p>Carrier is determined based on the device's SIM (for GSM devices), not the current roaming carrier.</p></li></ul> </td> </tr> <tr> @@ -404,22 +404,22 @@ country (as determined by SIM carrier) in which paid apps are available.</p></td Android NDK?</a></p> </tr> <tr> <td valign="top">Copy-Protected Applications</td> <td valign="top"><p>To copy protect an application, set copy protection to "On" when you configure publishing -options for your application. Market will not show copy-protected applications on +options for your application. Google Play will not show copy-protected applications on developer devices or unreleased devices.</p></td> </tr> </table> <h2 id="MultiApks">Publishing Multiple APKs with Different Filters</h2> -<p>Some specific Android Market filters allow you to publish multiple APKs for the same +<p>Some specific Google Play filters allow you to publish multiple APKs for the same application in order to provide a different APK to different device configurations. For example, if you're creating a video game that uses high-fidelity graphic assets, you might want to create two APKs that each support different texture compression formats. This way, you can reduce the size of the APK file by including only the textures that are required for each device -configuration. Depending on each device's support for your texture compression formats, Android -Market will deliver it the APK that you've declared to support that device.</p> +configuration. Depending on each device's support for your texture compression formats, Google +Play will deliver it the APK that you've declared to support that device.</p> -<p>Currently, Android Market allows you to publish multiple APKs for the same application only +<p>Currently, Google Play allows you to publish multiple APKs for the same application only when each APK provides different filters based on the following configurations:</p> <ul> <li>OpenGL texture compression formats @@ -440,7 +440,7 @@ href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code </ul> <p>All other filters still work the same as usual, but these three are the only filters that can -distinguish one APK from another within the same application listing on Android Market. For example, +distinguish one APK from another within the same application listing on Google Play. For example, you <em>cannot</em> publish multiple APKs for the same application if the APKs differ only based on whether the device has a camera.</p> @@ -450,5 +450,5 @@ APK that supports a wide range of device configurations</strong>. Publishing mul requires that you follow specific rules within your filters and that you pay extra attention to the version codes for each APK to ensure proper update paths for each configuration.</p> -<p>If you need more information about how to publish multiple APKs on Android Market, read <a +<p>If you need more information about how to publish multiple APKs on Google Play, read <a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/developing/building/building-cmdline.jd b/docs/html/guide/developing/building/building-cmdline.jd index c43962a..fd90b1a 100644 --- a/docs/html/guide/developing/building/building-cmdline.jd +++ b/docs/html/guide/developing/building/building-cmdline.jd @@ -202,12 +202,12 @@ ant release <ol> <li> - <strong>Open the SDK and AVD Manager and launch a virtual device</strong> + <strong>Open the AVD Manager and launch a virtual device</strong> - <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool with no - arguments:</p> + <p>From your SDK's <code>platform-tools/</code> directory, execute the {@code android} tool +with the <code>avd</code> options:</p> <pre> -android +android avd </pre> <p>In the <em>Virtual Devices</em> view, select an AVD and click <strong>Start</strong>.</p> @@ -237,7 +237,7 @@ adb -s emulator-5554 install <em>path/to/your/app</em>.apk </ol> <p>If you don't see your application on the emulator, try closing the emulator and launching the - virtual device again from the SDK and AVD Manager. Sometimes when you install an application for the + virtual device again from the AVD Manager. Sometimes when you install an application for the first time, it won't show up in the application launcher or be accessible by other applications. This is because the package manager usually examines manifests completely only on emulator startup.</p> diff --git a/docs/html/guide/developing/building/index.jd b/docs/html/guide/developing/building/index.jd index 59c4645..569cd28 100644 --- a/docs/html/guide/developing/building/index.jd +++ b/docs/html/guide/developing/building/index.jd @@ -27,8 +27,8 @@ page.title=Building and Running <p>To run an application on an emulator or device, the application must be signed using debug or release mode. You typically want to sign your application in debug mode when you develop and test your application, because the build tools use a debug key with a known password so you do not have - to enter it every time you build. When you are ready to release the application to Android - Market, you must sign the application in release mode, using your own private key.</p> + to enter it every time you build. When you are ready to release the application to Google + Play, you must sign the application in release mode, using your own private key.</p> <p>Fortunately, Eclipse or your Ant build script signs the application for you in debug mode when you build your application. You can also easily setup Eclipse or your Ant build to sign your diff --git a/docs/html/guide/developing/debugging/ddms.jd b/docs/html/guide/developing/debugging/ddms.jd index 4398ec9..80b1e47 100644 --- a/docs/html/guide/developing/debugging/ddms.jd +++ b/docs/html/guide/developing/debugging/ddms.jd @@ -11,7 +11,19 @@ parent.link=index.html <li><a href="#running">Running DDMS</a></li> <li><a href="#how-ddms-works">How DDMS Interacts with a Debugger</a></li> - <li><a href="#using-ddms">Using DDMS</a></li> + <li><a href="#using-ddms">Using DDMS</a> + <ol> + <li><a href="#heap">Viewing heap usage for a process</a></li> + <li><a href="#alloc">Tracking memory allocation of objects</a></li> + <li><a href="#emulator">Working with an emulator or device's file system</a></li> + <li><a href="#thread">Examining thread information</a></li> + <li><a href="#profiling">Starting method profiling</a></li> + <li><a href="#network">Using the Network Traffic tool</a></li> + <li><a href="#logcat">Using LogCat</a></li> + <li><a href="#ops-location">Emulating phone operations and location</a></li> + </ol> + + </li> </ol> </div> </div> @@ -90,7 +102,7 @@ parent.link=index.html <a href="#running">Running DDMS</a>. - <h3>Viewing heap usage for a process</h3> + <h3 id="heap">Viewing heap usage for a process</h3> <p>DDMS allows you to view how much heap memory a process is using. This information is useful in tracking heap usage at a certain point of time during the execution of your application.</p> @@ -110,7 +122,7 @@ parent.link=index.html allocated for a particular memory size in bytes.</li> </ol> - <h3>Tracking memory allocation of objects</h3> + <h3 id="alloc">Tracking memory allocation of objects</h3> <p>DDMS provides a feature to track objects that are being allocated to memory and to see which classes and threads are allocating the objects. This allows you to track, in real time, where @@ -140,7 +152,7 @@ parent.link=index.html line number of the code that allocated the object.</li> </ol> - <h3>Working with an emulator or device's file system</h3> + <h3 id="emulator">Working with an emulator or device's file system</h3> <p>DDMS provides a File Explorer tab that allows you to view, copy, and delete files on the device. This feature is useful in examining files that are created by your application or if you @@ -160,7 +172,7 @@ parent.link=index.html <!-- Need to elaborate more on where things are stored in the file system, databases, apks, user info, files that are important to look at --> - <h3>Examining thread information</h3> + <h3 id="thread">Examining thread information</h3> <p>The Threads tab in DDMS shows you the currently running threads for a selected process.</p> @@ -204,6 +216,67 @@ parent.link=index.html Profiling</strong>.</li> </ol> + <h3 id="network">Using the Network Traffic tool</h3> + + <p>In Android 4.0, the DDMS (Dalvik Debug Monitor Server) includes a Detailed +Network Usage tab that makes it possible to track when your application is +making network requests. Using this tool, you can monitor how and when your app +transfers data and optimize the underlying code appropriately. You can also +distinguish between different traffic types by applying a “tag” to network +sockets before use.</p> + +<p>These tags are shown in a stack area chart in DDMS, as shown in figure 2:</p> + +<img src="{@docRoot}images/developing/ddms-network.png" /> +<p class="img-caption"><strong>Figure 2.</strong> Network Usage tab.</p> + +<p>By monitoring the frequency of your data transfers, and the amount of data +transferred during each connection, you can identify areas of your application +that can be made more battery-efficient. Generally, you should look for +short spikes that can be delayed, or that should cause a later transfer to be +pre-empted. </p> + +<p>To better identify the cause of transfer spikes, the +{@link android.net.TrafficStats} API allows you +to tag the data transfers occurring within a thread using {@link +android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()}, followed +by manually tagging (and untagging) individual sockets using {@link +android.net.TrafficStats#tagSocket tagSocket()} and {@link +android.net.TrafficStats#untagSocket untagSocket()}. For example:</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); +TrafficStats.tagSocket(outputSocket); +// Transfer data using socket +TrafficStats.untagSocket(outputSocket);</pre> + +<p>Alternatively, the Apache {@link org.apache.http.client.HttpClient} and +{@link java.net.URLConnection} APIs included in the platform +automatically tag sockets internally based on the active tag (as +identified by +{@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()}). +These APIs correctly tag/untag sockets when recycled through +keep-alive pools. In the following example, +{@link android.net.TrafficStats#setThreadStatsTag setThreadStatsTag()} +sets the active tag to be {@code 0xF00D}. +There can only be one active tag per thread. +That is the value that will +be returned by {@link android.net.TrafficStats#getThreadStatsTag getThreadStatsTag()} +and thus used by {@link org.apache.http.client.HttpClient} + to tag sockets. The {@code finally} statement +invokes +{@link android.net.TrafficStats#clearThreadStatsTag clearThreadStatsTag()} +to clear the tag.</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); + try { + // Make network request using HttpClient.execute() + } finally { + TrafficStats.clearThreadStatsTag(); +}</pre> + +<p>Socket tagging is supported in Android 4.0, but real-time stats will only be +displayed on devices running Android 4.0.3 or higher.</p> + <h3 id="logcat">Using LogCat</h3> <p>LogCat is integrated into DDMS, and outputs the messages that you print out using the {@link android.util.Log} @@ -230,7 +303,7 @@ parent.link=index.html with the log tags or with the process id that generated the log message. The add filter, edit filter, and delete filter buttons let you manage your custom filters.</p> - <h3>Emulating phone operations and location</h3> + <h3 id="ops-location">Emulating phone operations and location</h3> <p>The Emulator control tab lets you simulate a phone's voice and data network status. This is useful when you want to test your application's robustness in differing network environments.</p> diff --git a/docs/html/guide/developing/device.jd b/docs/html/guide/developing/device.jd index d22dca1..d91551a 100644 --- a/docs/html/guide/developing/device.jd +++ b/docs/html/guide/developing/device.jd @@ -134,11 +134,11 @@ above.</p> </tr> <tr> <td>ASUS</td> - <td><code>0B05</code></td> + <td><code>0b05</code></td> </tr> <tr> <td>Dell</td> - <td><code>413C</code></td> + <td><code>413c</code></td> </tr> <tr> <td>Foxconn</td> @@ -146,35 +146,35 @@ above.</p> </tr> <tr> <td>Fujitsu</td> - <td><code>04C5</code></td> + <td><code>04c5</code></td> </tr> <tr> <td>Fujitsu Toshiba</td> - <td><code>04C5</code></td> + <td><code>04c5</code></td> </tr> <tr> <td>Garmin-Asus</td> - <td><code>091E</code></td> + <td><code>091e</code></td> </tr> <tr> <td>Google</td> - <td><code>18D1</code></td> + <td><code>18d1</code></td> </tr> <tr> <td>Hisense</td> - <td><code>109B</code></td> + <td><code>109b</code></td> </tr> <tr> <td>HTC</td> - <td><code>0BB4</code></td> + <td><code>0bb4</code></td> </tr> <tr> <td>Huawei</td> - <td><code>12D1</code></td> + <td><code>12d1</code></td> </tr> <tr> <td>K-Touch</td> - <td><code>24E3</code></td> + <td><code>24e3</code></td> </tr> <tr> <td>KT Tech</td> @@ -185,8 +185,8 @@ above.</p> <td><code>0482</code></td> </tr> <tr> - <td>Lenevo</td> - <td><code>17EF</code></td> + <td>Lenovo</td> + <td><code>17ef</code></td> </tr> <tr> <td>LG</td> @@ -194,7 +194,7 @@ above.</p> </tr> <tr> <td>Motorola</td> - <td><code>22B8</code></td> + <td><code>22b8</code></td> </tr> <tr> <td>NEC</td> @@ -214,11 +214,11 @@ above.</p> </tr> <tr> <td>Pantech</td> - <td><code>10A9</code></td> + <td><code>10a9</code></td> </tr> <tr> <td>Pegatron</td> - <td><code>1D4D</code></td> + <td><code>1d4d</code></td> </tr> <tr> <td>Philips</td> @@ -226,31 +226,31 @@ above.</p> </tr> <tr> <td>PMC-Sierra</td> - <td><code>04DA</code></td> + <td><code>04da</code></td> </tr> <tr> <td>Qualcomm</td> - <td><code>05C6</code></td> + <td><code>05c6</code></td> </tr> <tr> <td>SK Telesys</td> - <td><code>1F53</code></td> + <td><code>1f53</code></td> </tr> <tr> <td>Samsung</td> - <td><code>04E8</code></td> + <td><code>04e8</code></td> </tr> <tr> <td>Sharp</td> - <td><code>04DD</code></td> + <td><code>04dd</code></td> </tr> <tr> <td>Sony</td> - <td><code>054C</code></td> + <td><code>054c</code></td> </tr> <tr> <td>Sony Ericsson</td> - <td><code>0FCE</code></td> + <td><code>0fce</code></td> </tr> <tr> <td>Teleepoch</td> @@ -262,6 +262,6 @@ above.</p> </tr> <tr> <td>ZTE</td> - <td><code>19D2</code></td> + <td><code>19d2</code></td> </tr> </table> diff --git a/docs/html/guide/developing/devices/emulator.jd b/docs/html/guide/developing/devices/emulator.jd index 02dcb68..5edd1f5 100644 --- a/docs/html/guide/developing/devices/emulator.jd +++ b/docs/html/guide/developing/devices/emulator.jd @@ -9,28 +9,58 @@ parent.link=index.html <h2>In this document</h2> <ol> <li><a href="#overview">Overview</a></li> + <li><a href="#avds">Android Virtual Devices and the Emulator</a></li> <li><a href="#starting">Starting and Stopping the Emulator</a></li> - <li><a href="#starting">Android Virtual Devices and the Emulator</a></li> - <li><a href="#controlling">Controlling the Emulator</a></li> - <li><a href="#startup-options">Emulator Startup Options</a></li> + <li><a href="#apps">Installing Applications on the Emulator</a></li> + <li><a href="#acceleration">Using Hardware Acceleration</a> + <ol> + <li><a href="#accel-graphics">Configuring Graphics Acceleration</a></li> + <li><a href="#accel-vm">Configuring Virtual Machine Acceleration</a></li> + </ol> + </li> + <li><a href="#sdcard">SD Card Emulation</a> + <ol> + <li><a href="#sdcard-creating">Creating an SD card image</a></li> + <li><a href="#sdcard-files">Copying files to an SD card image</a></li> + <li><a href="#sdcard-loading">Loading an SD card image</a></li> + </ol> + </li> <li><a href="#diskimages">Working with Emulator Disk Images</a> <ol> - <li><a href="#defaultimages">Default Images</a></li> - <li><a href="#runtimeimages">Runtime Images: User Data and SD Card</a></li> - <li><a href="#temporaryimages">Temporary Images</a></li> + <li><a href="#defaultimages">Default image files</a></li> + <li><a href="#runtimeimages">Runtime images: user data and SD card</a></li> + <li><a href="#temporaryimages">Temporary images</a></li> </ol> </li> <li><a href="#emulatornetworking">Emulator Networking</a> <ol> <li><a href="#networkaddresses">Network Address Space</a></li> <li><a href="#networkinglimitations">Local Networking Limitations</a></li> - <li><a href="#redirections">Using Network Redirections</a></li> + <li><a href="#redirection">Using Network Redirection</a></li> <li><a href="#dns">Configuring the Emulator's DNS Settings</a></li> <li><a href="#proxy">Using the Emulator with a Proxy</a></li> <li><a href="#connecting">Interconnecting Emulator Instances</a></li> <li><a href="#calling">Sending a Voice Call or SMS to Another Emulator Instance</a></li> </ol> </li> + <li><a href="#console">Using the Emulator Console</a> + <ol> + <li><a href="#portredirection">Port Redirection</a></li> + <li><a href="#geo">Geo Location Provider Emulation</a></li> + <li><a href="#events">Hardware Events Emulation</a></li> + <li><a href="#power">Device Power Characteristics</a></li> + <li><a href="#netstatus">Network Status</a></li> + <li><a href="#netdelay">Network Delay Emulation</a></li> + <li><a href="#netspeed">Network Speed Emulation</a></li> + <li><a href="#telephony">Telephony Emulation</a></li> + <li><a href="#sms">SMS Emulation</a></li> + <li><a href="#vm">VM State</a></li> + <li><a href="#window">Emulator Window</a></li> + <li><a href="#terminating">Terminating an Emulator Instance</a></li> + </ol> + </li> + <li><a href="#limitations">Emulator Limitations</a></li> + <li><a href="#troubleshooting">Troubleshooting Emulator Problems</a></li> </ol> <h2>See also</h2> @@ -44,7 +74,7 @@ parent.link=index.html <img src="{@docRoot}images/emulator-wvga800l.png" alt="Image of the Android Emulator" width="367" height="349" style="margin-left:2em;float:right;"/> <p>The Android SDK includes a virtual mobile device emulator -that runs on your computer. The emulator lets you prototype, develop, and test +that runs on your computer. The emulator lets you prototype, develop and test Android applications without using a physical device. </p> <p>The Android emulator mimics all of the hardware and software features @@ -52,7 +82,7 @@ of a typical mobile device, except that it cannot place actual phone calls. It provides a variety of navigation and control keys, which you can "press" using your mouse or keyboard to generate events for your application. It also provides a screen in which your application is displayed, together with any other -Android applications running. </p> +active Android applications. </p> <p>To let you model and test your application more easily, the emulator utilizes Android Virtual Device (AVD) configurations. AVDs let you define certain hardware @@ -62,35 +92,34 @@ the emulator, it can use the services of the Android platform to invoke other applications, access the network, play audio and video, store and retrieve data, notify the user, and render graphical transitions and themes. </p> -<p>The emulator also includes a variety of debug capabilities, such as a console -from which you can log kernel output, simulate application interrupts (such as -arriving SMS messages or phone calls), and simulate latency effects and dropouts -on the data channel.</p> +<p>The emulator also includes a variety of debug capabilities, such as a console +from which you can log kernel output, simulate application interrupts (such as +arriving SMS messages or phone calls), and simulate latency effects and dropouts +on the data network.</p> -<h2 id="overview">Overview</h2> +<h2 id="overview">Overview</h2> -<p>The Android emulator is a QEMU-based application that provides a virtual ARM +<p>The Android emulator is an application that provides a virtual mobile device on which you can run your Android applications. It runs a full Android system stack, down to the kernel level, that includes a set of preinstalled applications (such as the dialer) that you can access from your applications. You can choose what version of the Android system you want to run in the emulator by configuring AVDs, and you can also customize the mobile device skin and key mappings. When launching the emulator and at runtime, -you can use a variety of commands and options to control the its behaviors. +you can use a variety of commands and options to control its behavior. </p> -<p>The Android system image distributed in the SDK contains ARM machine code for -the Android Linux kernel, the native libraries, the Dalvik VM, and the various -Android package files (such as for for the Android framework and preinstalled -applications). The emulator's QEMU layers provide dynamic binary translation of -the ARM machine code to the OS and processor architecture of your development -machine. </p> +<p>The Android system images available through the Android SDK Manager contain +code for the Android Linux kernel, the native libraries, the Dalvik VM, and the +various Android packages (such as the Android framework and preinstalled +applications). The emulator provides dynamic binary translation of device +machine code to the OS and processor architecture of your development +machine.</p> -<p>Adding custom capabilities to the underlying QEMU services, the Android -emulator supports many hardware features likely to be found on mobile devices, -including: </p> +<p>The Android emulator supports many hardware features likely to be found on +mobile devices, including: </p> <ul> <li>An ARMv5 CPU and the corresponding memory-management unit (MMU)</li> @@ -101,41 +130,37 @@ buttons)</li> <li>Flash memory partitions (emulated through disk image files on the development machine)</li> <li>A GSM modem, including a simulated SIM Card</li> + <li>A camera, using a webcam connected to your development computer.</li> + <li>Sensors like an accelerometer, using data from a USB-connected Android device.</li> </ul> -<p>The sections below provide more information about the emulator and how to use -it for developing Android applications.</p> - +<p>The following sections describe the emulator and its use for development of Android +applications in more detail.</p> -<a name="avds"></a> -<h2>Android Virtual Devices and the Emulator</h2> +<h2 id="avds">Android Virtual Devices and the Emulator</h2> <p>To use the emulator, you first must create one or more AVD configurations. In each configuration, you specify an Android platform to run in the emulator and the set of hardware options and emulator skin you want to use. Then, when you launch the emulator, you specify the AVD configuration that you want to load. </p> -<p>To specify the AVD you want to load when starting the emulator, you use the -<code>-avd</code> argument, as shown in the previous section. </p> - <p>Each AVD functions as an independent device, with its own private storage for user data, SD card, and so on. When you launch the emulator with an AVD configuration, it automatically loads the user data and SD card data from the AVD directory. By default, the emulator stores the user data, SD card data, and cache in the AVD directory.</p> <p>To create and manage AVDs you use the AVD Manager UI or the <code>android</code> tool -that is included in the SDK. +that is included in the SDK. For complete information about how to set up AVDs, see <a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> -<a name="starting"></a> -<h2>Starting and Stopping the Emulator</h2> +<h2 id="starting">Starting and Stopping the Emulator</h2> <p>During development and testing of your application, you install and run your application in the Android emulator. You can launch the emulator as a standalone -application, from a command line, or you can use it as part of your Eclipse +application from a command line, or you can run it from within your Eclipse development environment. In either case, you specify the AVD configuration to load and any startup options you want to use, as described in this document. </p> @@ -144,20 +169,24 @@ load and any startup options you want to use, as described in this document. depending on your needs, you can start multiple emulator instances and run your application in more than one emulated device. You can use the emulator's built-in commands to simulate GSM phone calling or SMS between emulator -instances, and you can set up network redirections that allow emulators to send +instances, and you can set up network redirection that allows emulators to send data to one another. For more information, see <a href="#telephony">Telephony Emulation</a>, <a href="#sms">SMS Emulation</a>, and <a href="#emulatornetworking">Emulator Networking</a></p> -<p>To start an instance of the emulator from the command line, change to the +<p>To start an instance of the emulator from the command line, navigate to the <code>tools/</code> folder of the SDK. Enter <code>emulator</code> command like this: </p> -<pre>emulator -avd <avd_name></pre> +<pre>emulator -avd <avd_name> [<options>]</pre> + +<p>This initializes the emulator, loads an AVD configuration and displays the emulator +window. For more information about command line options for the emulator, see the +<a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool reference.</p> -<p>This initializes the emulator and loads an AVD configuration (see the next -section for more information about AVDs). You will see the emulator window -appear on your screen. </p> +<p class="note"><strong>Note:</strong> You can run multiple +instances of the emulator concurrently, each with its own AVD configuration and +storage area for user data, SD card, and so on.</p> <p>If you are working in Eclipse, the ADT plugin for Eclipse installs your application and starts the emulator automatically, when you run or debug @@ -171,585 +200,435 @@ on the Emulator</a> for information about how to install your application.</p> <p>To stop an emulator instance, just close the emulator's window.</p> <p>For a reference of the emulator's startup commands and keyboard mapping, see -the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> document.</p> +the <a href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> tool +reference.</p> + + +<h2 id="apps">Installing Applications on the Emulator</h2> + +<p>If you don't have access to Eclipse or the ADT Plugin, you can install your application on the +emulator using the <a href="{@docRoot}guide/developing/tools/adb.html#move">adb</a> utility. Before +installing the application, you need to build and package it into an <code>.apk</code> as described +in <a href="{@docRoot}guide/developing/building/index.html">Building and +Running Apps</a>. Once the application is installed, you can start the emulator from the command +line as described previously, using any startup options necessary. +When the emulator is running, you can also connect to the emulator instance's +<a href="#console">console</a> to issue commands as needed.</p> + +<p>As you update your code, you periodically package and install it on the emulator. +The emulator preserves the application and its state data across restarts, +in a user-data disk partition. To ensure that the application runs properly +as you update it, you may need to delete the emulator's user-data partition. +To do so, start the emulator with the <code>-wipe-data</code> option. +For more information about the user-data partition and other emulator storage, +see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> +<h2 id="acceleration">Using Hardware Acceleration</h2> +<p>In order to make the Android emulator run faster and be more responsive, you can configure it to +take advantage of hardware acceleration, using a combination of configuration options, specific +Android system images and hardware drivers.</p> -<a name="controlling"></a> +<h3 id="accel-graphics">Configuring Graphics Acceleration</h3> +<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the graphics +acceleration feature for the emulator is experimental; be alert for incompatibilities and +errors when using this feature. </p> -<h2>Controlling the Emulator</h2> +<p>Graphics acceleration for the emulator takes advantage of your development computer's graphics +hardware, specifically its graphics processing unit (GPU), to make screen drawing faster. To use +the graphics acceleration feature, you must have the following versions of the Android development +tools installed:</p> -<p>You can use emulator <a href="#startup-options">startup options</a> and <a -href="#console">console commands</a> to control the behaviors and -characteristics of the emulated environment itself. -</p> +<ul> + <li>Android SDK Tools, Revision 17 or higher</li> + <li>Android SDK Platform API 15, Revision 3 or higher</li> +</ul> -<p>When the emulator is running, you can interact with the emulated mobile -device just as you would an actual mobile device, except that you use your mouse -pointer to "touch" the touchscreen and your keyboard keys to -"press" the simulated device keys. </p> +<p>Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK +Manager</a> to install these components:</p> -<p>The table below summarizes the mappings between the emulator keys and and -the keys of your keyboard. </p> +<p class="note"><strong>Note:</strong> Not all applications are compatible with graphics hardware +acceleration. In particular, the Browser application and applications using the {@link +android.webkit.WebView} component are not compatible with graphics acceleration.</p> -<table border="0" style="clear:left;"> - <tr> - <th>Emulated Device Key </th> - <th>Keyboard Key </th> - </tr> - <tr> - <td>Home</td> - <td>HOME</td> - </tr> - <tr> - <td>Menu (left softkey)</td> - <td>F2 <em>or</em> Page-up button</td> - </tr> - <tr> - <td>Star (right softkey)</td> - <td>Shift-F2 <em>or </em>Page Down</td> - </tr> - <tr> - <td>Back</td> - <td>ESC</td> - </tr> - <tr> - <td>Call/dial button </td> - <td>F3</td> - </tr> - <tr> - <td>Hangup/end call button</td> - <td>F4</td> - </tr> - <tr> - <td>Search</td> - <td>F5 </td> - </tr> - <tr> - <td>Power button</td> - <td>F7 </td> - </tr> - <tr> - <td>Audio volume up button</td> - <td>KEYPAD_PLUS, Ctrl-5</td> - </tr> +<p>To configure an AVD to use graphics acceleration:</p> - <tr> - <td>Audio volume down button</td> - <td>KEYPAD_MINUS, Ctrl-F6</td> - </tr> - <tr> - <td>Camera button</td> - <td>Ctrl-KEYPAD_5, Ctrl-F3</td> - </tr> - <tr> - <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, Ctrl-F11</td> - </tr> - <tr> - <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, Ctrl-F12</td> - </tr> - <tr> - <td>Toggle cell networking on/off</td> - <td>F8</td> - </tr> - <tr> - <td>Toggle code profiling</td> - <td>F9 (only with <code>-trace</code> startup option)</td> - </tr> - <tr> - <td>Toggle fullscreen mode</td> - <td>Alt-Enter</td> - </tr> - <tr> - <td>Toggle trackball mode</td> - <td>F6</td> - </tr> - <tr> - <td>Enter trackball mode temporarily (while key is pressed)</td> - <td>Delete</td> - </tr> - <tr> - <td>DPad left/up/right/down</td> - <td>KEYPAD_4/8/6/2</td> - </tr> - <tr> - <td>DPad center click</td> - <td>KEYPAD_5</td> - </tr> - <tr> - <td>Onion alpha increase/decrease</td> - <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> - </tr> -</table> +<ol> + <li>Make sure you have the required SDK components installed (listed above).</li> + <li>Start the AVD Manager and create a new AVD with the <strong>Target</strong> value of +<strong>Android 4.0.3 (API Level 15)</strong>, revision 3 or higher.</li> + <li>If you want to have graphics acceleration enabled by default for this AVD, in the +<strong>Hardware</strong> section, click <strong>New</strong>, select <strong>GPU emulation</strong> +and set the value to <strong>Yes</strong>. + <p class="note"><strong>Note:</strong> You can also enable graphics acceleration when you +start an emulator using command line options as describe in the next section.</p> + </li> + <li>Name the AVD instance and select any other configuration options. + <p class="caution"><strong>Caution:</strong> Do not select the <strong>Snapshot: Enabled</strong> +option. Snapshots are not supported for emulators with graphics acceleration enabled.</p> + </li> + <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> +</ol> -<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> +<p>If you set <strong>GPU emulation</strong> to <strong>Yes</strong> for your AVD, then graphics +acceleration is automatically enabled when you run it. If you did not enable <strong>GPU +emulation</strong> when you created the AVD, you can still enable it at runtime.</p> -<h2 id="emulator">Emulator Startup Options</h2> +<p>To enable graphics acceleration at runtime for an AVD:</p> -<p>The emulator supports a variety of options that you can specify -when launching the emulator, to control its appearance or behavior. -Here's the command-line usage for launching the emulator with options: </p> +<ul> + <li>If you are running the emulator from the command line, just include the {@code -gpu on} +option: +<pre>emulator -avd <avd_name> -gpu on</pre> + <p class="note"><strong>Note:</strong> You must specify an AVD configuration that uses +Android 4.0.3 (API Level 15, revision 3) or higher system image target. Graphics acceleration is not +available for earlier system images.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application using an AVD with +the {@code -gpu on} option enabled: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the AVD you created in the previous procedure.</li> + <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter:<br> + {@code -gpu on}</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> -<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> -<p>The table below summarizes the available options.</p> +<h3 id="accel-vm">Configuring Virtual Machine Acceleration</h2> -<table> -<tr> - <th width="10%" >Category</th> - <th width="20%" >Option</th> - <th width="30%" >Description</th> - <th width="40%" >Comments</th> -</tr> +<p class="caution"><strong>Caution:</strong> As of SDK Tools Revision 17, the virtual machine +acceleration feature for the emulator is experimental; be alert for incompatibilities and errors +when using this feature.</p> + +<p>Many modern CPUs provide extensions for running virtual machines (VMs) more efficiently. Taking +advantage of these extensions with the Android emulator requires some additional configuration of +your development system, but can significantly improve the execution speed. Before attempting to use +this type of acceleration, you should first determine if your development system’s CPU supports one +of the following virtualization extensions technologies:</p> -<tr> - <td rowspan="9">Help</td> - <td><code>-help</code></td> - <td>Print a list of all emulator options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-all</code></td> - <td>Print help for all startup options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-<option></code></td> - <td>Print help for a specific startup option.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-debug-tags</code></td> - <td>Print a list of all tags for <code>-debug <tags></code>.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-disk-images</code></td> - <td>Print help for using emulator disk images.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-environment</code></td> - <td>Print help for emulator environment variables.</td> - <td> </td> -</tr><tr> - <td><code>-help-keys</code></td> - <td>Print the current mapping of keys.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-keyset-file</code></td> - <td>Print help for defining a custom key mappings file.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-virtual-device</code></td> - <td>Print help for Android Virtual Device usage.</td> - <td> </td> -</tr> -<tr> - <td>AVD</td> - <td><code>-avd <avd_name></code> or <br> - <code>@<avd_name></code></td> - <td><strong>Required</strong>. Specifies the AVD to load for this emulator - instance.</td> - <td>You must create an AVD configuration before launching the emulator. For - information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing - Virtual Devices with AVD Manager</a>.</td> -<tr> - <td rowspan="7">Disk Images</td> - <td><code>-cache <filepath></code></td> - <td>Use <filepath> as the working cache partition image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If no cache file is specified, the emulator's default behavior is to use a temporary file instead. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> -</td></tr> -<tr> - <td><code>-data <filepath></code></td> - <td>Use <filepath> as the working user-data disk image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the storage area of the AVD being used (see <code>-avd</code>). -</td></tr> -<!-- -<tr> - <td><code>-datadir <dir></code></td> - <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> - <td><code><dir></code> is a path relative to the current working directory. - -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image -in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information -on disk images, use <code>-help-disk-images</code>.</p> -</td></tr> ---> -<!-- -<tr> - <td><code>-image <filepath></code></td> - <td>Use <filepath> as the system image.</td> - <td>Optionally, you can specify a path relative to the current working directory. - Default is <system>/system.img.</td> -</tr> ---> -<tr> - <td><code>-initdata <filepath></code></td> - <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents - of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> - <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> -</tr> -<!-- -<tr> - <td><code>-kernel <filepath></code></td> - <td>Use <filepath> as the emulated kernel.</td> - <td>Optionally, you can specify a path relative to the current working directory. </td> -</tr> ---> -<tr> - <td><code>-nocache</code></td> - <td>Start the emulator without a cache partition.</td> - <td>See also <code>-cache <file></code>.</td> -</tr> -<tr> - <td><code>-ramdisk <filepath></code></td> - <td>Use <filepath> as the ramdisk image.</td> - <td>Default value is <code><system>/ramdisk.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. - For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<tr> - <td><code>-sdcard <filepath></code></td> - <td>Use <file> as the SD card image.</td> - <td>Default value is <code><system>/sdcard.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<!-- -<tr> - <td><code>-system <dirpath></code></td> - <td>Search for system, ramdisk and user data images in <dir>.</td> - <td><code><dir></code> is a directory path relative to the current - working directory.</td> -</tr> ---> -<tr> - <td><code>-wipe-data</code></td> - <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and - <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, - then copies the contents of the file at <code>-inidata</code> data to the image file before starting. - </td> - <td>See also <code>-initdata</code>. - <p>For more information on disk images, use <code>-help-disk-images</code>.</p> -</td> -</tr> -<tr> - <td rowspan="9">Debug</td> - <td><code>-debug <tags></code></td> - <td>Enable/disable debug messages for the specified debug tags.</td> - <td><code><tags></code> is a space/comma/column-separated list of debug component names. - Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> -</tr> -<tr> - <td><code>-debug-<tag></code></td> - <td>Enable/disable debug messages for the specified debug tag.</td> - <td rowspan="2">Use <code>-help-debug-tags</code> to print a list of debug component names that you can use in <code><tag></code>. </td> -</tr> -<tr> - <td><code>-debug-no-<tag></code></td> - <td>Disable debug messages for the specified debug tag.</td> -</tr> -<tr> - <td><code>-logcat <logtags></code></td> - <td>Enable logcat output with given tags.</td> - <td>If the environment variable ANDROID_LOG_TAGS is defined and not - empty, its value will be used to enable logcat output by default.</td> -</tr> -<tr> - <td><code>-shell</code></td> - <td>Create a root shell console on the current terminal.</td> - <td>You can use this command even if the adb daemon in the emulated system is broken. - Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> -</tr> -<tr> - <td><code>-shell-serial <device></code></td> - <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character - device to use for communication with the shell.</td> - <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at - <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a> - for a list of device types. - -<p>Here are some examples: </p> <ul> - <li><code>-shell-serial stdio</code> is identical to <code>-shell</code></li> - <li><code>-shell-serial tcp::4444,server,nowait</code> lets you communicate with the shell over TCP port 4444</li> - <li><code>-shell-serial fdpair:3:6</code> lets a parent process communicate with the shell using fds 3 (in) and 6 (out)</li> - <li><code>-shell-serial fdpair:0:1</code> uses the normal stdin and stdout fds, except that QEMU won't tty-cook the data.</li> - </ul> -</td> -</tr> -<tr> - <td><code>-show-kernel <name></code></td> - <td>Display kernel messages.</td> - <td> </td> -</tr> -<tr> - <td><code>-trace <name></code></td> - <td>Enable code profiling (press F9 to start), written to a specified file.</td> - <td> </td> -</tr> -<tr> - <td><code>-verbose</code></td> - <td>Enable verbose output.</td> - <td>Equivalent to <code>-debug-init</code>. -<p>You can define the default verbose output options used by emulator instances in the Android environment variable -ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: -<code>-debug-<tags>.</code> </p> -<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: -<p><code>ANDROID_VERBOSE=init,modem</code></p> -<p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> -</td> -</tr> -<tr> - <td rowspan="6">Media</td> - <td><code>-audio <backend></code></td> - <td>Use the specified audio backend.</td> - <td> </td> -</tr> -<tr> - <td><code>-audio-in <backend></code></td> - <td>Use the specified audio-input backend.</td> - <td> </td> -</tr> -<tr> - <td><code>-audio-out <backend></code></td> - <td>Use the specified audio-output backend.</td> - <td> </td> -</tr> -<!--<tr> - <td><code>-mic <device or file></code></td> - <td>Use device or WAV file for audio input.</td> - <td> </td> -</tr> ---> -<tr> - <td><code>-noaudio</code></td> - <td>Disable audio support in the current emulator instance.</td> - <td> </td> -</tr> -<tr> - <td><code>-radio <device></code></td> - <td>Redirect radio modem interface to a host character device.</td> - <td> </td></tr> -<tr> - <td><code>-useaudio</code></td> - <td>Enable audio support in the current emulator instance.</td> - <td>Enabled by default. </td> -</tr> + <li>Intel Virtualization Technology (VT, VT-x, vmx) extensions</li> + <li>AMD Virtualization (AMD-V, SVM) extensions (only supported for Linux)</li> +</ul> -<tr> - <td rowspan="7">Network</td> - <td><code>-dns-server <servers></code></td> - <td>Use the specified DNS server(s). </td> - <td>The value of <code><servers></code> must be a comma-separated list of up to 4 DNS server names or - IP addresses.</td> -</tr> -<tr> - <td><code>-http-proxy <proxy></code></td> - <td>Make all TCP connections through a specified HTTP/HTTPS proxy</td> - <td>The value of <code><proxy></code> can be one of the following:<br> - <code>http://<server>:<port></code><br> - <code>http://<username>:<password>@<server>:<port></code> - <p>The <code>http://</code> prefix can be omitted. If the <code>-http-proxy <proxy></code> command is not supplied, - the emulator looks up the <code>http_proxy</code> environment variable and automatically uses any value matching - the <code><proxy></code> format described above.</p></td> -</tr> -<tr> - <td><code>-netdelay <delay></code></td> - <td>Set network latency emulation to <delay>.</td> - <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for - supported <code><delay></code> values. </td> -</tr> -<tr> - <td><code>-netfast</code></td> - <td>Shortcut for <code>-netspeed full -netdelay none</code></td> - <td> </td></tr> -<tr> - <td><code>-netspeed <speed></code></td> - <td>Set network speed emulation to <speed>.</td> - <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for - supported <code><speed></code> values. </td> -</tr> -<tr> - <td><code>-port <port></code></td> - <td>Set the console port number for this emulator instance to <code><port></code>.</td> - <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 - must also be free and will be reserved for ADB.</td> -</tr> -<tr> - <td><code>-report-console <socket></code></td> - <td>Report the assigned console port for this emulator instance to a remote third party - before starting the emulation. </td> - <td><code><socket></code> must use one of these formats: +<p>The specifications from the manufacturer of your CPU should indicate if it supports +virtualization extensions. If your CPU does not support one of these virtualization technologies, +then you cannot use virtual machine acceleration.</p> -<p><code>tcp:<port>[,server][,max=<seconds>]</code></br> -<code>unix:<port>[,server][,max=<seconds>]</code></p> +<p class="note"><strong>Note:</strong> Virtualization extensions are typically enabled through +your computer's BIOS and are frequently turned off by default. Check the documentation for your +system's motherboard to find out how to enable virtualization extensions.</p> -<p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> -</tr> -<tr> - <td rowspan="8">System</td> - <td><code>-cpu-delay <delay></code></td> - <td>Slow down emulated CPU speed by <delay> </td> - <td>Supported values for <delay> are integers between 0 and 1000. - -<p>Note that the <delay> does not correlate to clock speed or other absolute metrics -— it simply represents an abstract, relative delay factor applied non-deterministically -in the emulator. Effective performance does not always -scale in direct relationship with <delay> values.</p> -</td> -</tr> -<tr> - <td><code>-gps <device></code></td> - <td>Redirect NMEA GPS to character device.</td> - <td>Use this command to emulate an NMEA-compatible GPS unit connected to - an external character device or socket. The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at - <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. -</td> -</tr> -<tr> - <td><code>-nojni</code></td> - <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> -<tr> - <td><code>-qemu</code></td> - <td>Pass arguments to qemu.</td> - <td> </td></tr> -<tr> - <td><code>-qemu -h</code></td> - <td>Display qemu help.</td> - <td></td></tr> -<tr> - <td><code>-radio <device></code></td> - <td>Redirect radio mode to the specified character device.</td> - <td>The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at -<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. -</td> -</tr> -<tr> - <td><code>-timezone <timezone></code></td> - <td>Set the timezone for the emulated device to <timezone>, instead of the host's timezone.</td> - <td><code><timezone></code> must be specified in zoneinfo format. For example: -<p>"America/Los_Angeles"<br> -"Europe/Paris"</p> -</td> -</tr> -<tr> - <td><code>-version</code></td> - <td>Display the emulator's version number.</td> - <td> </td> -</tr> -<tr> - <td rowspan="12">UI</td> - <td><code>-dpi-device <dpi></code></td> - <td>Scale the resolution of the emulator to match the screen size - of a physical device.</td> - <td>The default value is 165. See also <code>-scale</code>.</td> -</tr> -<tr> - <td><code>-no-boot-anim</code></td> - <td>Disable the boot animation during emulator startup.</td> - <td>Disabling the boot animation can speed the startup time for the emulator.</td> -</tr> -<tr> - <td><code>-no-window</code></td> - <td>Disable the emulator's graphical window display.</td> - <td> </td> -</tr> -<tr> - <td><code>-scale <scale></code></td> - <td>Scale the emulator window. </td> - <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" - tells the emulator to select the best window size.</td> -</tr> -<tr> - <td><code>-raw-keys</code></td> - <td>Disable Unicode keyboard reverse-mapping.</td> - <td> </td></tr> -<tr> - <td><code>-noskin</code></td> - <td>Don't use any emulator skin.</td> - <td> </td></tr> -<tr> - <td><code>-keyset <file></code></td> - <td>Use the specified keyset file instead of the default.</td> - <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. - For more information, use <code>-help-keyset</code> to print information about this topic. -</td> -</tr> -<tr> - <td><code>-onion <image></code></td> - <td>Use overlay image over screen.</td> - <td>No support for JPEG. Only PNG is supported.</td></tr> -<tr> - <td><code>-onion-alpha <percent></code></td> - <td>Specify onion skin translucency value (as percent). - <td>Default is 50.</td> -</tr> -<tr> - <td><code>-onion-rotation <position></code></td> - <td>Specify onion skin rotation. - <td><code><position></code> must be one of the values 0, 1, 2, 3.</td> -</tr> -<tr> - <td><code>-skin <skinID></code></td> - <td>This emulator option is deprecated. </td> - <td>Please set skin options using AVDs, rather than by using this emulator -option. Using this option may yield unexpected and in some cases misleading -results, since the density with which to render the skin may not be defined. -AVDs let you associate each skin with a default density and override the default -as needed. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices -with AVD Manager</a>. -</td> -</tr> -<tr> - <td><code>-skindir <dir></code></td> - <td>This emulator option is deprecated. </td> - <td>See comments for <code>-skin</code>, above.</td></tr> -</table> +<p>Once you have determined that your CPU supports virtualization extensions, make sure you can work +within these additional requirements of running an emulator inside an accelerated virtual +machine:</p> + +<ul> + <li><strong>x86 AVD Only</strong> - You must use an AVD that is uses an x86 system image target. +AVDs that use ARM-based system images cannot be accelerated using the emulator configurations +described here.</li> + <li><strong>Not Inside a VM</strong> - You cannot run a VM-accelerated emulator inside another +virtual machine, such as a VirtualBox or VMWare-hosted virtual machine. You must run the emulator +directly on your system hardware.</li> + <li><strong>Other VM Drivers</strong> - If you are running another virtualization technology on +your system such as VirtualBox or VMWare, you may need to unload the driver for that virtual machine +hosting software before running an accelerated emulator.</li> + <li><strong>OpenGL® Graphics</strong> - Emulation of OpenGL ES graphics may not perform at the +same level as an actual device.</li> +</ul> + +<p>To use virtual machine acceleration with the emulator, you need the following version of Android +development tools. Use the <a href="{@docRoot}sdk/installing.html#AddingComponents">Android SDK +Manager</a> to install these components:</p> + +<ul> + <li>Android SDK Tools, Revision 17 or higher</li> + <li>Android x86-based system image</li> +</ul> + +<p>If your development environment meets all of the requirements for running a VM-accelerated +emulator, you can use the AVD Manager to create an x86-based AVD configuration:</p> + +<ol> + <li>In the Android SDK Manager, make sure you have an x86-based <strong>System Image</strong> + installed for your target Android version. If you do not have an x86 <strong>System + Image</strong> installed, select one in the Android SDK Manager and install it. + <p class="note"><strong>Tip:</strong> System images are listed under each API Level in the SDK + Manager. An x86 system image may not be available for all API levels.</p> + </li> + <li>Start the AVD Manager and create a new AVD with an x86 value for the +<strong>CPU/ABI</strong> field. You may need to select a specific <strong>Target</strong> value, or +select a <strong>Target</strong> value and then select a specific <strong>CPU/ABI</strong> +option.</li> + <li>Name the emulator instance and select any other configuration options.</li> + <li>Click <strong>Create AVD</strong> to save the emulator configuration.</li> +</ol> + +<h4 id="vm-windows">Configuring VM Acceleration on Windows</h4> + +<p>Virtual machine acceleration for Windows requires the installation of the Intel Hardware +Accelerated Execution Manager (Intel HAXM). The software requires an Intel CPU with +Virtualization Technology (VT) support and one of the following operating systems:</p> + +<ul> + <li>Windows 7 (32/64-bit)</li> + <li>Windows Vista (32/64-bit)</li> + <li>Windows XP (32-bit only)</li> +</ul> + +<p>To install the virtualization driver:</p> + +<ol> + <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel +Hardware Accelerated Execution Manager</strong>.</li> + <li>After the download completes, execute {@code +<sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.exe}.</li> + <li>Follow the on-screen instructions to complete installation.</li> + <li>After installation completes, confirm that the virtualization driver is operating correctly by +opening a command prompt window and running the following command: + <pre>sc query intelhaxm</pre> + <p>You should see a status message including the following information:</p> +<pre> +SERVICE_NAME: intelhaxm + ... + STATE : 4 RUNNING + ... +</pre> + </li> +</ol> + +<p>To run an x86-based emulator with VM acceleration:</p> +<ul> + <li>If you are running the emulator from the command line, just specify an x86-based AVD: +<pre>emulator -avd <avd_name></pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running +its installer.</p> + +<p>You can stop using the virtualization driver by uninstalling it. Re-run the installer or use +the Control Panel to remove the software.</p> + + +<h4 id="vm-mac">Configuring VM Acceleration on Mac</h4> + +<p>Virtual machine acceleration on a Mac requires the installation of the Intel Hardware Accelerated +Execution Manager (Intel HAXM) kernel extension to allow the Android emulator to make use of CPU +virtualization extensions. The kernel extension is compatible with Mac OS X Snow Leopard (version +10.6.0) and higher.</p> + +<p>To install the Intel HAXM kernel extension:</p> + +<ol> + <li>Start the Android SDK Manager, select <strong>Extras</strong> and then select <strong>Intel +Hardware Accelerated Execution Manager</strong>. + <li>After the download completes, execute + {@code <sdk>/extras/intel/Hardware_Accelerated_Execution_Manager/IntelHAXM.dmg}.</li> + <li>Double click the <strong>IntelHAXM.mpkg</strong> icon to begin installation.</li> + <li>Follow the on-screen instructions to complete installation.</li> + <li>After installation completes, confirm that the new kernel extension is operating correctly by +opening a terminal window and running the following command: + <pre>kextstat | grep intel</pre> + <p>You should see a status message containing the following extension name, indicating that the + kernel extension is loaded:</p> + <pre>com.intel.kext.intelhaxm</pre> + </li> +</ol> + +<p>To run an x86-based emulator with VM acceleration:</p> +<ul> + <li>If you are running the emulator from the command line, just specify an x86-based AVD: +<pre>emulator -avd <avd_name></pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p>You can adjust the amount of memory available to the Intel HAXM kernel extension by re-running +the installer.</p> + +<p>You can stop using the virtualization kernel driver by uninstalling it. Before removing it, shut +down any running x86 emulators. To unload the virtualization kernel driver, run the following +command in a terminal window:</p> + +<pre>sudo /System/Library/Extensions/intelhaxm.kext/Contents/Resources/uninstall.sh</pre> + +<h4 id="vm-linux">Configuring VM Acceleration on Linux</h4> + +<p>Linux-based systems support virtual machine acceleration through the KVM software package. Follow +<a href="https://www.google.com/?q=kvm+installation">instructions for installing KVM</a> on your +Linux system, and verify that KVM is enabled. In addition to following the installation +instructions, be aware of these configuration requirements:</p> + +<ul> + <li>Running KVM requires specific user permissions, make sure you have sufficient permissions +according to the KVM installation instructions.</li> + <li>If you use another virtualization technology in your Linux platform, unload its kernel driver +before running the x86 emulator. For example, the VirtualBox driver program is {@code vboxdrv}.</li> +</ul> + +<p>To run an x86-based emulator with VM acceleration:</p> + +<ul> + <li>If you are running the emulator from the command line, start the emulator with an x86-based +AVD and include the KVM options: +<pre>emulator -avd <avd_name> -qemu -m 512 -enable-kvm</pre> + <p class="note"><strong>Note:</strong> You must provide an x86-based AVD configuration +name, otherwise VM acceleration will not be enabled.</p> + </li> + <li>If you are running the emulator from Eclipse, run your Android application with an x86-based +AVD and include the KVM options: + <ol> + <li>In Eclipse, click your Android project folder and then select <strong>Run > Run +Configurations...</strong></li> + <li>In the left panel of the <strong>Run Configurations</strong> dialog, select your Android +project run configuration or create a new configuration.</li> + <li>Click the <strong>Target</strong> tab.</li> + <li>Select the x86-based AVD you created previously.</li> + <li>In the <strong>Additional Emulator Command Line Options</strong> field, enter: + <pre>-qemu -m 512 -enable-kvm</pre> + </li> + <li>Run your Android project using this run configuration.</li> + </ol> + </li> +</ul> + +<p class="note"><strong>Important:</strong> When using the {@code -qemu} command line option, make sure +it is the last parameter in your command. All subsequent options are interpreted as qemu-specific +parameters.</p> + + +<h2 id="sdcard">SD Card Emulation</h2> + +<p>You can create a disk image and then load it to the emulator at startup, to +simulate the presence of a user's SD card in the device. To do this, you can specify +an SD card image when you create an AVD, or you can use the mksdcard utility included +in the SDK.</p> + +<p>The following sections describe how to create an SD card disk image, how to copy +files to it, and how to load it in the emulator at startup. </p> + +<p>Note that you can only load a disk image at emulator startup. Similarly, you +can not remove a simulated SD card from a running emulator. However, you can +browse, send files to, and copy/remove files from a simulated SD card either +with adb or the emulator. </p> + +<p>The emulator supports emulated SDHC cards, so you can create an SD card image +of any size up to 128 gigabytes.</p> + + +<h3 id="sdcard-creating">Creating an SD card image</h3> + +<p>There are several ways of creating an SD card image. The easiest way is to use the +<strong>AVD Manager</strong> to create a new SD card by specifying a size when you create an AVD. +You can also use the {@code android} command line tool when creating an AVD. Just add the +<code>-c</code> option to your command: </p> + +<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> + +<p>The <code>-c</code> option can also be used to to specify a path to an SD card +image for the new AVD. For more information, see <a +href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices +from the Command Line</a>. +</p> + +<p>You can also use the mksdcard tool, included in the SDK, to create a FAT32 disk +image that you can load in the emulator at startup. You can access mksdcard in +the tools/ directory of the SDK and create a disk image like this: </p> + +<pre>mksdcard <size> <file></pre> + +<p>For example:</p> + +<pre>mksdcard 1024M sdcard1.iso</pre> + +<p>For more information, see <a +href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p> + + +<h3 id="sdcard-files">Copying files to an SD card image</h3> + +<p>Once you have created the disk image, you can copy files to it prior to +loading it in the emulator. To copy files, you can mount the image as a loop +device and then copy the files to it, or you can use a utility such as {@code mtools} to +copy the files directly to the image. The {@code mtools} package is available for Linux, +Mac, and Windows.</p> + +<p>Alternatively, you can use the {@code adb push} command to move files onto an SD card image +while it is loaded in an emulator. For more information see the <a +href="{@docRoot}guide/developing/tools/adb.html#copyfiles">{@code adb push}</a> documentation.</p> + +<h3 id="sdcard-loading">Loading an SD card image</h3> +<p>By default, the emulator loads the SD card image that is stored with the active +AVD (see the <code>-avd</code> startup option).</p> + +<p>Alternatively, you can start the emulator with the +<code>-sdcard</code> flag and specify the name and path of your image (relative +to the current working directory): </p> + +<pre>emulator -sdcard <filepath></pre> -<a name="diskimages"></a> -<h2>Working with Emulator Disk Images</h2> +<h2 id="diskimages">Working with Emulator Disk Images</h2> <p>The emulator uses mountable disk images stored on your development machine to -simulate flash (or similar) partitions on an actual device. For example, it uses +simulate flash (or similar) partitions on an actual device. For example, it uses a disk image containing an emulator-specific kernel, the Android system, a ramdisk image, and writeable images for user data and simulated SD card.</p> <p>To run properly, the emulator requires access to a specific set of disk image -files. By default, the Emulator always looks for the disk images in the -private storage area of the AVD in use. If no images exist there when -the Emulator is launched, it creates the images in the AVD directory based on +files. By default, the Emulator always looks for the disk images in the +private storage area of the AVD in use. If no images exist there when +the Emulator is launched, it creates the images in the AVD directory based on default versions stored in the SDK. </p> -<p class="note"><strong>Note:</strong> The default storage location for -AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and -Settings\<user>\.android\</code> on Windows XP, and +<p class="note"><strong>Note:</strong> The default storage location for +AVDs is in <code>~/.android/avd</code> on OS X and Linux, <code>C:\Documents and +Settings\<user>\.android\</code> on Windows XP, and <code>C:\Users\<user>\.android\</code> on Windows Vista.</p> <p>To let you use alternate or custom versions of the image files, the emulator provides startup options that override the default locations and filenames of -the image files. When you use the options, the emulator searches for the image +the image files. When you use one of these options, the emulator searches for the image file under the image name or location that you specify; if it can not locate the image, it reverts to using the default names and location.</p> @@ -757,20 +636,19 @@ image, it reverts to using the default names and location.</p> image files, and temporary image files. The sections below describe how to override the location/name of each type of file. </p> -<a name="defaultimages"></a> -<h3>Default Images</h3> +<h3 id="defaultimages">Default image files</h3> -<p>When the emulator launches but does not find an existing user data image in +<p>When the emulator launches, but does not find an existing user data image in the active AVD's storage area, it creates a new one from a default version -included in the SDK. The default user data image is read-only. The image +included in the SDK. The default user data image is read-only. The image files are read-only.</p> <p>The emulator provides the <code>-system <dir></code> startup option to -let you override the location under which the emulator looks for the default +let you override the location where the emulator looks for the default user data image. </p> <p>The emulator also provides a startup option that lets you override the name -of the default user data image, as described in the table below. When you use the +of the default user data image, as described in the following table. When you use the option, the emulator looks in the default directory, or in a custom location (if you specified <code>-system <dir></code>). </p> @@ -810,25 +688,24 @@ option, the emulator looks in the default directory, or in a custom location </table> -<a name="runtimeimages"></a> -<h3>Runtime Images: User Data and SD Card</h3> +<h3 id="runtimeimages">Runtime images: user data and SD card</h3> -<p>At runtime, the emulator reads and writes data on two disk images: a -user-data image and (optionally) an SD card image. This emulates the user-data +<p>At runtime, the emulator reads and writes data to two disk images: a +user-data image and (optionally) an SD card image. These images emulate the user-data partition and removable storage media on actual device. </p> -<p>The emulator provides a default user-data disk image. At startup, the emulator -creates the default image as a copy of the system user-data image (user-data.img), +<p>The emulator provides a default user-data disk image. At startup, the emulator +creates the default image as a copy of the system user-data image (user-data.img), described above. The emulator stores the new image with the files of the active AVD.</p> <!-- -<p>The emulator provides a startup option, <code>-datadir <dir></code>, +<p>The emulator provides a startup option, <code>-datadir <dir></code>, that you can use to override the location under which the emulator looks for the runtime image files. </p> --> -<p>The emulator provides startup options to let you override the actual names and storage -locations of the runtime images to load, as described in the table below. When you use one +<p>The emulator provides startup options to let you override the actual names and storage +locations of the runtime images to load, as described in the following table. When you use one of these options, the emulator looks for the specified file(s) in the current working directory, in the AVD directory, or in a custom location (if you specified a path with the filename). </p> @@ -842,7 +719,7 @@ in the AVD directory, or in a custom location (if you specified a path with the <td><code>userdata-qemu.img</code></td> <td>An image to which the emulator writes runtime user-data for a unique user.</td> <td>Override using <code>-data <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, +path the image, relative to the current working directory. If you supply a filename only, the emulator looks for the file in the current working directory. If the file at <code><filepath></code> does not exist, the emulator creates an image from the default userdata.img, stores it under the name you specified, and persists user data to it at shutdown. </td> @@ -852,7 +729,7 @@ specified, and persists user data to it at shutdown. </td> <td><code>sdcard.img</code></td> <td>An image representing an SD card inserted into the emulated device.</td> <td>Override using <code>-sdcard <filepath></code>, where <code><filepath></code> is the -path the image, relative to the current working directory. If you supply a filename only, +path the image, relative to the current working directory. If you supply a filename only, the emulator looks for the file in the current working directory. </td> </tr> @@ -864,38 +741,38 @@ the emulator looks for the file in the current working directory. </td> session-specific data. For example, it uses the image to store a unique user's installed application data, settings, databases, and files. </p> -<p>At startup, the emulator attempts to load a user-data image stored during -a previous session. It looks for the file in the current working directory, -in the AVD directory as described above, and at the custom location/name +<p>At startup, the emulator attempts to load a user-data image stored during +a previous session. It looks for the file in the current working directory, +in the AVD directory described in a previous section and at the custom location/name that you specified at startup. </p> <ul> -<li>If it finds a user-data image, it mounts the image and makes it available -to the system for reading/writing of user data. </li> +<li>If it finds a user-data image, it mounts the image and makes it available +to the system for reading and writing of user data. </li> <li>If it does not find one, it creates an image by copying the system user-data image (userdata.img), described above. At device power-off, the system persists -the user data to the image, so that it will be available in the next session. +the user data to the image, so that it will be available in the next session. Note that the emulator stores the new disk image at the location/name that you specify in <code>-data</code> startup option.</li> </ul> <p class="note"><strong>Note:</strong> Because of the AVD configurations used in the emulator, -each emulator instance now gets its own dedicated storage. There is no need +each emulator instance gets its own dedicated storage. There is no longer a need to use the <code>-d</code> option to specify an instance-specific storage area.</p> <h4>SD Card</h4> <P>Optionally, you can create a writeable disk image that the emulator can use -to simulate removeable storage in an actual device. For information about how to create an +to simulate removeable storage in an actual device. For information about how to create an emulated SD card and load it in the emulator, see <a href="#sdcard">SD Card Emulation</a></p> <p>You can also use the android tool to automatically create an SD Card image -for you, when creating an AVD. For more information, see <a +for you, when creating an AVD. For more information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices with AVD Manager</a>. -<a name="temporaryimages"></a> -<h3>Temporary Images</h3> + +<h3 id="temporaryimages">Temporary Images</h3> <p>The emulator creates two writeable images at startup that it deletes at device power-off. The images are: </p> @@ -909,8 +786,8 @@ device power-off. The images are: </p> persisting it at device power-off. </p> <p>The <code>/cache</code> partition image is initially empty, and is used by -the browser to cache downloaded web pages and images. The emulator provides an -<code>-cache <file></code>, which specifies the name of the file at which +the browser to cache downloaded web pages and images. The emulator provides an +<code>-cache <file></code>, which specifies the name of the file in which to persist the <code>/cache</code> image at device power-off. If <code><file> </code> does not exist, the emulator creates it as an empty file. </p> @@ -918,16 +795,14 @@ to persist the <code>/cache</code> image at device power-off. If <code><file& <code>-nocache</code> option at startup. </p> -<a name="emulatornetworking"></a> -<h2>Emulator Networking</h2> +<h2 id="emulatornetworking">Emulator Networking</h2> <p>The emulator provides versatile networking capabilities that you can use to set up complex modeling and testing environments for your application. The sections below introduce the emulator's network architecture and capabilities. </p> -<a name="networkaddresses"></a> -<h3>Network Address Space</h3> +<h3 id="networkaddresses">Network Address Space</h3> <p>Each instance of the emulator runs behind a virtual router/firewall service that isolates it from your development machine's network interfaces and settings @@ -990,14 +865,13 @@ specific to the Android emulator and will probably be very different on real devices (which are also very likely to be NAT-ed, i.e., behind a router/firewall)</p> -<a name="networkinglimitations"></a> -<h3>Local Networking Limitations</h3> -<p>Each emulator instance runs behind a virtual router, but unlike an actual -device connected to a physical router, the emulated device doesn't have access -to a physical network. Instead it runs as part of a normal application on your -development machine. This means that it is subject to the same networking -limitations as other applications on your machine:</p> +<h3 id="networkinglimitations">Local Networking Limitations</h3> + +<p>Android applications running in an emulator can connect to the network available on your +workstation. However, they connect through the emulator, not directly to hardware, and the emulator +acts like a normal application on your workstation. This means that the emulator, and thus your +Android applications, are subject to some limitations:</p> <ul> <li>Communication with the emulated device may be blocked by a firewall @@ -1016,25 +890,24 @@ host operating system and network.</p> protocols (such as ICMP, used for "ping") might not be supported. Currently, the emulator does not support IGMP or multicast. </p> -<a name="redirections"></a> -<h3>Using Network Redirections</h3> +<h3 id="redirection">Using Network Redirection</h3> <p>To communicate with an emulator instance behind its virtual router, you need -to set up network redirections on the virtual router. Clients can then connect +to set up network redirection on the virtual router. Clients can then connect to a specified guest port on the router, while the router directs traffic to/from that port to the emulated device's host port. </p> -<p>To set up the network redirections, you create a mapping of host and guest +<p>To set up the network redirection, you create a mapping of host and guest ports/addresses on the the emulator instance. There are two ways to set up -network redirections: using emulator console commands and using the ADB tool, as +network redirection: using emulator console commands and using the ADB tool, as described below. </p> -<a name="consoleredir"></a> -<h4>Setting up Redirections through the Emulator Console</h4> + +<h4 id="consoleredir">Setting up Redirection through the Emulator Console</h4> <p>Each emulator instance provides a control console the you can connect to, to issue commands that are specific to that instance. You can use the -<code>redir</code> console command to set up redirections as needed for an +<code>redir</code> console command to set up redirection as needed for an emulator instance. </p> <p>First, determine the console port number for the target emulator instance. @@ -1044,25 +917,25 @@ its console port number, as follows: </p> <pre><code>telnet localhost 5554</code></pre> -<p>Once connected, use the <code>redir</code> command to work with redirections. +<p>Once connected, use the <code>redir</code> command to work with redirection. To add a redirection, use:</p> <pre><code>add <protocol>:<host-port>:<guest-port></code> </pre> -<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, -and <code><host-port></code> and <code><guest-port></code> sets the +<p>where <code><protocol></code> is either <code>tcp</code> or <code>udp</code>, +and <code><host-port></code> and <code><guest-port></code> sets the mapping between your own machine and the emulated system, respectively. </p> -<p>For example, the following command sets up a redirection that will handle all +<p>For example, the following command sets up a redirection that handles all incoming TCP connections to your host (development) machine on 127.0.0.1:5000 and will pass them through to the emulated system's 10.0.2.15:6000.:</p> <pre>redir add tcp:5000:6000</pre> <p>To delete a redirection, you can use the <code>redir del</code> command. To -list all redirections for a specific instance, you can use <code>redir -list</code>. For more information about these and other console commands, see +list all redirection for a specific instance, you can use <code>redir +list</code>. For more information about these and other console commands, see <a href="#console">Using the Emulator Console</a>. </p> <p>Note that port numbers are restricted by your local environment. this typically @@ -1071,29 +944,28 @@ administrator privileges. Also, you won't be able to set up a redirection for a host port that is already in use by another process on your machine. In that case, <code>redir</code> generates an error message to that effect. </p> -<a name="adbredir"></a> -<h4>Setting Up Redirections through ADB</h4> +<h4 id="adbredir">Setting Up Redirection through ADB</h4> <p>The Android Debug Bridge (ADB) tool provides port forwarding, an alternate -way for you to set up network redirections. For more information, see <a +way for you to set up network redirection. For more information, see <a href="{@docRoot}guide/developing/tools/adb.html#forwardports">Forwarding Ports</a> in the ADB documentation.</p> <p>Note that ADB does not currently offer any way to remove a redirection, except by killing the ADB server.</p> -<a name="dns"></a> -<h3>Configuring the Emulator's DNS Settings</h3> + +<h3 id="dns">Configuring the Emulator's DNS Settings</h3> <p>At startup, the emulator reads the list of DNS servers that your system is currently using. It then stores the IP addresses of up to four servers on this list and sets up aliases to them on the emulated addresses 10.0.2.3, 10.0.2.4, 10.0.2.5 and 10.0.2.6 as needed. </p> -<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing -the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the -addresses by calling the <code>GetNetworkParams()</code> API. Note that this -usually means that the emulator ignores the content of your "hosts" file +<p>On Linux and OS X, the emulator obtains the DNS server addresses by parsing +the file <code>/etc/resolv.conf</code>. On Windows, the emulator obtains the +addresses by calling the <code>GetNetworkParams()</code> API. Note that this +usually means that the emulator ignores the content of your "hosts" file (<code>/etc/hosts</code> on Linux/OS X, <code>%WINDOWS%/system32/HOSTS</code> on Windows).</P> @@ -1104,8 +976,8 @@ list of server names or IP addresses. You might find this option useful if you encounter DNS resolution problems in the emulated network (for example, an "Unknown Host error" message that appears when using the web browser).</p> -<a name="proxy"></a> -<h3>Using the Emulator with a Proxy</h3> + +<h3 id="proxy">Using the Emulator with a Proxy</h3> <p>If your emulator must access the Internet through a proxy server, you can use the <code>-http-proxy <proxy></code> option when starting the emulator, to @@ -1132,18 +1004,18 @@ startup and uses its value automatically, if defined. </p> <p>You can use the <code>-verbose-proxy</code> option to diagnose proxy connection problems.</p> -<a name="connecting"></a> -<h3>Interconnecting Emulator Instances</h3> + +<h3 id="connecting">Interconnecting Emulator Instances</h3> <p>To allow one emulator instance to communicate with another, you must set up -the necessary network redirections as illustrated below. </p> +the necessary network redirection as illustrated below. </p> <p>Assume that your environment is</p> <ul> <li>A is you development machine</li> <li>B is your first emulator instance, running on A</li> - <li>C is your second emulator instance, running on A too</li> + <li>C is your second emulator instance, also running on A</li> </ul> <p>and you want to run a server on B, to which C will connect, here is how you @@ -1168,10 +1040,11 @@ B:10.0.2.15:<serverPort></code></li> <li>C connects to 10.0.2.2:8080</li> </ul> -<a name="calling"></a> -<h3>Sending a Voice Call or SMS to Another Emulator Instance</h3> +<h3 id="calling">Sending a Voice Call or SMS to Another Emulator Instance</h3> -<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to another. To send a voice call or SMS, you use the dialer application and SMS application (if available) installed on one emulator </p> +<p>The emulator automatically forwards simulated voice calls and SMS messages from one instance to +another. To send a voice call or SMS, use the dialer application or SMS application, respectively, +from one of the emulators.</p> <p>To initiate a simulated voice call to another emulator instance:</p> <ol> @@ -1186,16 +1059,23 @@ B:10.0.2.15:<serverPort></code></li> <p>You can also connect to an emulator instance's console to simulate an incoming voice call or SMS. For more information, see <a href="#telephony">Telephony Emulation</a> and <a href="#sms">SMS Emulation</a>. -<a name="console"></a> -<h2>Using the Emulator Console</h2> +<h2 id="console">Using the Emulator Console</h2> + +<p>Each running emulator instance provides a console that lets you query and control the emulated +device environment. For example, you can use the console to manage port redirection, network +characteristics, and telephony events while your application is running on the emulator. To +access the console and enter commands, use telnet to connect to the console's port number.</p> -<p>Each running emulator instance includes a console facility that lets you dynamically query and control the simulated device environment. For example, you can use the console to dynamically manage port redirections and network characteristics and simulate telephony events. To access the console and enter commands, you use telnet to connect to the console's port number. </p> <p>To connect to the console of any running emulator instance at any time, use this command: </p> <pre>telnet localhost <console-port></pre> -<p>An emulator instance occupies a pair of adjacent ports: a console port and an adb port. The port numbers differ by 1, with the adb port having the higher port number. The console of the first emulator instance running on a given machine uses console port 5554 and adb port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, 5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> +<p>An emulator instance occupies a pair of adjacent ports: a console port and an {@code adb} port. +The port numbers differ by 1, with the {@code adb} port having the higher port number. The console +of the first emulator instance running on a given machine uses console port 5554 and {@code adb} +port 5555. Subsequent instances use port numbers increasing by two — for example, 5556/5557, +5558/5559, and so on. Up to 16 concurrent emulator instances can run a console facility. </p> <p>To connect to the emulator console, you must specify a valid console port. If multiple emulator instances are running, you need to determine the console port of the emulator instance you want to connect to. You can find the instance's console port listed in the title of the instance window. For example, here's the window title for an instance whose console port is 5554:</p> @@ -1209,12 +1089,14 @@ B:10.0.2.15:<serverPort></code></li> <p>To exit the console session, use <code>quit</code> or <code>exit</code>.</p> -<p>The sections below describe the major functional areas of the console.</p> +<p>The following sections below describe the major functional areas of the console.</p> + -<a name="portredirection"></a> +<h3 id="portredirection">Port Redirection</h3> + +<p>You can use the console to add and remove port redirection while the emulator is running. After +you connect to the console, manage port redirection by entering the following command:</p> -<h3>Port Redirection</h3> -<p>You can use the console to add and remove port redirections while the emulator is running. After connecting to the console, you can manage port redirections in this way:</p> <pre>redir <list|add|del> </pre> <p>The <code>redir</code> command supports the subcommands listed in the table below. </p> @@ -1225,14 +1107,14 @@ B:10.0.2.15:<serverPort></code></li> <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>list</code></td> - <td>List the current port redirections.</td> + <td>List the current port redirection.</td> <td> </td> </tr> - + <tr> <td><code>add <protocol>:<host-port>:<guest-port></code></td> <td>Add a new port redirection.</td> @@ -1244,16 +1126,16 @@ B:10.0.2.15:<serverPort></code></li> <tr> <td><code>del <protocol>:<host-port></code></td> <td>Delete a port redirection.</td> -<td>See above for meanings of <protocol> and <host-port>.</td> +<td>The meanings of <protocol> and <host-port> are listed in the previous row.</td> </tr> </table> -<a name="geo"></a> -<h3>Geo Location Provider Emulation</h3> -<p>The console provides commands to let you set the geo position used by an emulator emulated device. -You can use the <code>geo</code> command to send a simple GPS fix to the emulator, without needing to -use NMEA 1083 formatting. The usage for the command is:</p> +<h3 id="geo">Geo Location Provider Emulation</h3> + +<p>You can use the console to set the geographic location reported to the applications running +inside an emulator. Use the <code>geo</code> command to send a simple GPS fix to the +emulator, with or without NMEA 1083 formatting:</p> <pre>geo <fix|nmea></pre> @@ -1261,11 +1143,11 @@ use NMEA 1083 formatting. The usage for the command is:</p> <table> <tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>fix <longitude> <latitude> [<altitude>]</code></td> <td>Send a simple GPS fix to the emulator instance.</td> @@ -1278,19 +1160,21 @@ use NMEA 1083 formatting. The usage for the command is:</p> </tr> </table> -<p>You can issue the <code>geo</code> command to fix the GPS location as soon as an emulator instance is running. -The emulator creates a mock location provider that sends it to GPS-aware applications as soon as they start and -register location listeners. Any application can query the location manager to obtain the current GPS fix for the -emulated device by calling: +<p>You can issue the <code>geo</code> command as soon as an emulator instance is running. The +emulator sets the location you enter by creating a mock location provider. This provider responds to +location listeners set by applications, and also supplies the location to the {@link +android.location.LocationManager}. Any application can query the location manager to obtain the +current GPS fix for the emulated device by calling: <pre>LocationManager.getLastKnownLocation("gps")</pre> -<p>For more information about the Location Manager, see {@link android.location.LocationManager} and its methods.</p> +<p>For more information about the Location Manager, see {@link android.location.LocationManager}. +</p> -<a name="events"></a> -<h3>Hardware Events Emulation</h3> +<h3 id="events">Hardware Events Emulation</h3> -<p>You can use the <code>event</code> command to send various events to the emulator.The usage for the command is: </p> +<p>The {@code event} console commands sends hardware events to the emulator. The syntax for this +command is as follows:</p> <pre>event <send|types|codes|text></pre> @@ -1302,7 +1186,7 @@ emulated device by calling: <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>send <type>:<code>:<value> [...]</code></td> <td>Send one or more events to the Android kernel. </td> @@ -1315,7 +1199,7 @@ emulated device by calling: </tr> <tr> <td><code>codes <type></code></td> - <td>List all <code><codes></code> string aliases supported by the <code>event</code> + <td>List all <code><codes></code> string aliases supported by the <code>event</code> subcommands for the specified <code><type></code>.</td> <td> </td> </tr> @@ -1326,10 +1210,11 @@ emulated device by calling: </tr> </table> -<a name="power"></a> -<h3>Device Power Characteristics</h3> -<p>You can use the <code>power</code> command to control the simulated power state of the emulator instance.The usage for the command is: </p> +<h3 id="power">Device Power Characteristics</h3> + +<p>The {@code power} command controls the power state reported by the emulator to applications. The +syntax for this command is as follows: </p> <pre>power <display|ac|status|present|health|capacity></pre> @@ -1341,7 +1226,7 @@ emulated device by calling: <th width="30%" >Description</th> <th width="35%">Comments</th> </tr> - + <tr> <td><code>display</code></td> <td>Display battery and charger state.</td> @@ -1375,23 +1260,32 @@ emulated device by calling: </tr> </table> -<a name="netstatus"></a> -<h3>Network Status</h3> + +<h3 id="netstatus">Network Status</h3> <p>You can use the console to check the network status and current delay and speed characteristics. To do so, connect to the console and use the <code>netstatus</code> command. Here's an example of the command and its output. </p> <pre>network status </pre> -<a name="netdelay"></a> -<h3>Network Delay Emulation</h3> -<p>The emulator lets you simulate various network latency levels, so that you can test your application in an environment more typical of the actual conditions in which it will run. You can set a latency level or range at emulator startup or you can use the console to change the latency dynamically, while the application is running in the emulator. </p> -<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a supported <code><delay></code> value, as listed in the table below. Here are some examples:</p> +<h3 id="netdelay">Network Delay Emulation</h3> + +<p>The emulator lets you simulate various network latency levels, so that you can test your +application in an environment more typical of the actual conditions in which it will run. You can +set a latency level or range at emulator startup or you can use the console to change the latency, +while the application is running in the emulator. </p> + +<p>To set latency at emulator startup, use the <code>-netdelay</code> emulator option with a +supported <code><delay></code> value, as listed in the table below. Here are some +examples:</p> + <pre>emulator -netdelay gprs emulator -netdelay 40 100</pre> -<p>To make dynamic changes to network delay while the emulator is running, connect to the console and use the <code>netdelay</code> command with a supported <code><delay></code> value from the table below. </p> +<p>To make changes to network delay while the emulator is running, connect to the console and use +the <code>netdelay</code> command with a supported <code><delay></code> value from the table +below.</p> <pre>network delay gprs</pre> @@ -1401,7 +1295,7 @@ emulator -netdelay 40 100</pre> <tr> <th width="30%" >Value</th> <th width="35%" >Description</th><th width="35%">Comments</th></tr> - + <tr><td><code>gprs</code></td><td>GPRS</td> <td>(min 150, max 550)</td> </tr> @@ -1421,19 +1315,22 @@ emulator -netdelay 40 100</pre> <td> </td></tr> </table> -<a name="netspeed"></a> -<h3>Network Speed Emulation</h3> -<p>The emulator also lets you simulate various network transfer rates. -You can set a transfer rate or range at emulator startup or you can use the console to change the rate dynamically, -while the application is running in the emulator.</p> +<h3 id="netspeed">Network Speed Emulation</h3> + +<p>The emulator also lets you simulate various network transfer rates. +You can set a transfer rate or range at emulator startup or you can use the console to change the +rate, while the application is running in the emulator.</p> <p>To set the network speed at emulator startup, use the <code>-netspeed</code> emulator option with a supported <code><speed></code> value, as listed in the table below. Here are some examples:</p> + <pre>emulator -netspeed gsm emulator -netspeed 14.4 80</pre> -<p>To make dynamic changes to network speed while the emulator is running, connect to the console and use the <code>netspeed</code> command with a supported <code><speed></code> value from the table below. </p> +<p>To make changes to network speed while the emulator is running, connect to the console and use +the <code>netspeed</code> command with a supported <code><speed></code> value from the table +below.</p> <pre>network speed 14.4 80</pre> @@ -1444,7 +1341,7 @@ kilobits/sec):</p> <tr> <th width="30%">Value</th> <th width="35%">Description</th><th width="35%">Comments</th></tr> - + <tr> <td><code>gsm</code></td> <td>GSM/CSD</td><td>(Up: 14.4, down: 14.4)</td></tr> @@ -1476,14 +1373,19 @@ kilobits/sec):</p> <td>Set exact rates for upload and download separately.</td><td></td></tr> </table> -<a name="telephony"></a> -<h3>Telephony Emulation</h3> +<h3 id="telephony">Telephony Emulation</h3> + +<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony +functions in the emulator. For example, you can simulate inbound phone calls, establish data +connections and terminate them. The Android system handles simulated calls exactly as it would +actual calls. The emulator does not support call audio.</p> + +<p>You can use the {@code gsm} command to access the emulator's telephony functions after connecting +to the console. The syntax for this command is as follows:</p> -<p>The Android emulator includes its own GSM emulated modem that lets you simulate telephony functions in the emulator. For example, you can simulate inbound phone calls and establish/terminate data connections. The Android system handles simulated calls exactly as it would actual calls. The emulator does not support call audio in this release. </p> -<p>You can use the console to access the emulator's telephony functions. After connecting to the console, you can use</p> <pre>gsm <call|accept|busy|cancel|data|hold|list|voice|status> </pre> -<p>to invoke telephony functions. </p> + <p>The <code>gsm</code> command supports the subcommands listed in the table below. </p> <table> <tr> @@ -1559,11 +1461,12 @@ kilobits/sec):</p> </tr> </table> -<a name="sms"></a> -<h3>SMS Emulation</h3> +<h3 id="sms">SMS Emulation</h3> -<p>The Android emulator console lets you generate an SMS message and direct it to an emulator instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using this command:</p> +<p>The Android emulator console lets you generate an SMS message and direct it to an emulator +instance. Once you connect to an emulator instance, you can generate an emulated incoming SMS using +the following command:</p> <pre>sms send <senderPhoneNumber> <textmessage></pre> @@ -1571,11 +1474,11 @@ kilobits/sec):</p> <p>The console forwards the SMS message to the Android framework, which passes it through to an application that handles that message type. </p> -<a name="vm"></a> -<h3>VM State</h3> +<h3 id="vm">VM State</h3> -<p>You can use the <code>vm</code> command to control the VM on an emulator instance.The usage for the command is: </p> +<p>You can use the <code>vm</code> command to control the VM on an emulator instance. The syntax for +this command is as follows: </p> <pre>vm <start|stop|status></pre> @@ -1583,8 +1486,8 @@ kilobits/sec):</p> <table> <tr> - <th width="25%" >Subcommand </th> - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> <tr> @@ -1605,11 +1508,10 @@ kilobits/sec):</p> </table> -<a name="window"></a> +<h3 id="window">Emulator Window</h3> -<h3>Emulator Window</h3> - -<p>You can use the <code>window</code> command to manage the emulator window. The usage for the command is: </p> +<p>You can use the <code>window</code> command to manage the emulator window. The syntax for this +command is as follows: </p> <pre>window <scale></pre> @@ -1617,158 +1519,53 @@ kilobits/sec):</p> <table> <tr> - <th width="25%" >Subcommand - <th width="30%" >Description</th> + <th width="25%">Subcommand</th> + <th width="30%">Description</th> <th width="35%">Comments</th> </tr> <tr> <td><code>scale <scale></code></td> <td>Scale the emulator window.</td> - <td><scale> must be a number between 0.1 and 3 that describes the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + <td>A number between 0.1 and 3 that sets the scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.</td> </tr> </table> -<a name="terminating"></a> - -<h3>Terminating an Emulator Instance</h3> +<h3 id="terminating">Terminating an Emulator Instance</h3> <p>You can terminate an emulator instance through the console, using the <code>kill</code> command.</p> -<a name="skins"></a> - -<h2>Using Emulator Skins</h2> - -<p>The Android SDK includes several Emulator skins that you can use to control the resolution and density of the emulated device's screen. To select a specific skin for running the emulator, create an AVD that uses that skin. Please do not use deprecated emulator options such as <code>-skin</code> to control the skin used by an emulator instance. For more information about AVDs, see <a -href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> - - -<a name="multipleinstances"></a> - -<h2>Running Multiple Emulator Instances</h2> - -<p>Through the AVDs configurations used by the emulator, you can run multiple -instances of the emulator concurrently, each with its own AVD configuration and -storage area for user data, SD card, and so on. You no longer need to use the -<code>-d</code> option when launching the emulator, to point to an -instance-specific storage area. </p> - -<a name="apps"></a> - -<h2>Installing Applications on the Emulator</h2> - -<p>If you don't have access to Eclipse or the ADT Plugin, you can install -your application on the emulator <a href="{@docRoot}guide/developing/tools/adb.html#move">using -the adb utility</a>. Before installing the application, you need to build and package it -into an <code>.apk</code> as described in <a href="{@docRoot}guide/developing/building/index.html">Building and -Running Apps</a>. Once the application is installed, you can start the emulator from the command -line, as described in this document, using any startup options necessary. -When the emulator is running, you can also connect to the emulator instance's -console to issue commands as needed.</p> - -<p>As you update your code, you periodically package and install it on the emulator. -The emulator preserves the application and its state data across restarts, -in a user-data disk partition. To ensure that the application runs properly -as you update it, you may need to delete the emulator's user-data partition. -To do so, start the emulator with the <code>-wipe-data</code> option. -For more information about the user-data partition and other emulator storage, -see <a href="#diskimages">Working with Emulator Disk Images</a>.</p> +<h2 id="limitations">Emulator Limitations</h2> -<a name="sdcard"></a> -<a name="creating"></a> - -<h2>SD Card Emulation</h2> - -<p>You can create a disk image and then load it to the emulator at startup, to -simulate the presence of a user's SD card in the device. To do this, you can use -the android tool to create a new SD card image with a new AVD, or you can use -the mksdcard utility included in the SDK. </p> - -<p>The sections below describe how to create an SD card disk image, how to copy -files to it, and how to load it in the emulator at startup. </p> - -<p>Note that you can only load disk image at emulator startup. Similarly, you -can not remove a simulated SD card from a running emulator. However, you can -browse, send files to, and copy/remove files from a simulated SD card either -with adb or the emulator. </p> - -<p>The emulator supports emulated SDHC cards, so you can create an SD card image -of any size up to 128 gigabytes.</p> - -<h3 id="creatinga">Creating an SD card image using the android tool</h3> - -<p>The easiest way to create a new SD card is to use the android tool. When -creating an AVD, you simply specify the <code>-c</code> option, like this: </p> - -<pre>android create avd -n <avd_name> -t <targetID> -c <size>[K|M]</pre> - -<p>You can also use the <code>-c</code> option to specify a path to an SD card -image to use in the new AVD. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing Virtual Devices -from the Command Line</a>. -</p> - -<h3 id="creatingm">Creating an SD card image using mksdcard</h3> - -<p>You can use the mksdcard tool, included in the SDK, to create a FAT32 disk -image that you can load in the emulator at startup. You can access mksdcard in -the tools/ directory of the SDK and create a disk image like this: </p> - -<pre>mksdcard <size> <file></pre> - -<p>For example:</p> - -<pre>mksdcard 1024M sdcard1.iso</pre> - -<p>For more information, see <a href="{@docRoot}guide/developing/tools/mksdcard.html"><code>mksdcard</code></a>.</p> - -<a name="copying"></a> -<h3>Copying Files to a Disk Image</h3> - -<p>Once you have created the disk image, you can copy files to it prior to -loading it in the emulator. To copy files, you can mount the image as a loop -device and then copy the files to it, or you can use a utility such as mtools to -copy the files directly to the image. The mtools package is available for Linux, -Mac, and Windows.</p> - -<a name="loading"></a> -<a name="step3" id="step3"></a> - -<h3>Loading the Disk Image at Emulator Startup</h3> - -<p>By default, the emulator loads the SD card image that is stored with the active -AVD (see the <code>-avd</code> startup option).</p> - -<p>Alternatively, you ca start the emulator with the -<code>-sdcard</code> flag and specify the name and path of your image (relative -to the current working directory): </p> - -<pre>emulator -sdcard <filepath></pre> +<p>The functional limitations of the emulator include: </p> +<ul> + <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed + and received) through the emulator console, however. </li> + <li>No support for USB connections</li> + <li>No support for device-attached headphones</li> + <li>No support for determining network connected state</li> + <li>No support for determining battery charge level and AC charging state</li> + <li>No support for determining SD card insert/eject</li> + <li>No support for Bluetooth</li> +</ul> -<a name="troubleshooting"></a> -<h2>Troubleshooting Emulator Problems</h2> +<h2 id="troubleshooting">Troubleshooting Emulator Problems</h2> -<p>The adb utility sees the emulator as an actual physical device. For this reason, you might have to use the -d flag with some common adb commands, such as <code>install</code>. The -d flag lets you specify which of several connected devices to use as the target of a command. If you don't specify -d, the emulator will target the first device in its list. For more information about adb, see <a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p> +<p>The {@code adb} utility sees the emulator as an actual physical device. For this reason, you +might have to use the {@code -d} flag with some common {@code adb} commands, such as +<code>install</code>. The {@code -d} flag lets you specify which of several connected devices to use +as the target of a command. If you don't specify {@code -d}, the emulator targets the first +device in its list. For more information about {@code adb}, see <a +href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a>.</p> -<p>For emulators running on Mac OS X, if you see an error "Warning: No DNS servers found" when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If not, please run the following line in a command window:</p> +<p>For emulators running on Mac OS X, if you see an error {@code Warning: No DNS servers found} +when starting the emulator, check to see whether you have an <code>/etc/resolv.conf</code> file. If +not, please run the following line in a command window:</p> <pre>ln -s /private/var/run/resolv.conf /etc/resolv.conf</pre> -<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more troubleshooting information. </p> - -<a name="limitations"></a> - <h2>Emulator Limitations</h2> - <p>In this release, the limitations of the emulator include: </p> - <ul> - <li>No support for placing or receiving actual phone calls. You can simulate phone calls (placed and received) through the emulator console, however. </li> - <li>No support for USB connections</li> - <li>No support for camera/video capture (input).</li> - <li>No support for device-attached headphones</li> - <li>No support for determining connected state</li> - <li>No support for determining battery charge level and AC charging state</li> - <li>No support for determining SD card insert/eject</li> - <li>No support for Bluetooth</li> - </ul> +<p>See <a href="{@docRoot}resources/faq/index.html">Frequently Asked Questions</a> for more +troubleshooting information. </p> diff --git a/docs/html/guide/developing/devices/index.jd b/docs/html/guide/developing/devices/index.jd index a7d00f3..64651a1 100644 --- a/docs/html/guide/developing/devices/index.jd +++ b/docs/html/guide/developing/devices/index.jd @@ -7,9 +7,9 @@ page.title=Managing Virtual Devices <p>The easiest way to create an AVD is to use the graphical <a href= "{@docRoot}guide/developing/devices/managing-avds.html">AVD Manager</a>, which you launch - from Eclipse by clicking <strong>Window > Android SDK and AVD Manager</strong>. You can also start - the AVD Manager from the command line by calling the <code>android</code> tool in the <strong>tools</strong> - directory of the Android SDK.</p> + from Eclipse by clicking <strong>Window > AVD Manager</strong>. You can also start the AVD +Manager from the command line by calling the <code>android</code> tool with the <code>avd</code> +options, from the <strong><sdk>/tools/</strong> directory.</p> <p>You can also create AVDs on the command line by passing the <code>android</code> tool options. For more information on how to create AVDs in this manner, see <a href= diff --git a/docs/html/guide/developing/devices/managing-avds.jd b/docs/html/guide/developing/devices/managing-avds.jd index e70a0bb..412bd91 100644 --- a/docs/html/guide/developing/devices/managing-avds.jd +++ b/docs/html/guide/developing/devices/managing-avds.jd @@ -42,8 +42,8 @@ parent.link=index.html <li>Start the AVD Manager: <ul> - <li>In Eclipse: select <strong>Window > Android SDK and AVD Manager</strong>, or click - the Android SDK and AVD Manager icon in the Eclipse toolbar.</li> + <li>In Eclipse: select <strong>Window > AVD Manager</strong>, or click + the AVD Manager icon in the Eclipse toolbar.</li> <li>In other IDEs: Navigate to your SDK's <code>tools/</code> directory and execute the <code>android</code> tool with no arguments.</li> @@ -72,7 +72,7 @@ parent.link=index.html <li>Click <strong>Create AVD</strong>.</li> </ol> - <p>Your AVD is now ready and you can either close the SDK and AVD Manager, create more AVDs, or + <p>Your AVD is now ready and you can either close the AVD Manager, create more AVDs, or launch an emulator with the AVD by selecting a device and clicking <strong>Start</strong>.</p> <h3 id="hardwareopts">Hardware options</h3> diff --git a/docs/html/guide/developing/projects/index.jd b/docs/html/guide/developing/projects/index.jd index 63e67cd..b16e466 100644 --- a/docs/html/guide/developing/projects/index.jd +++ b/docs/html/guide/developing/projects/index.jd @@ -209,8 +209,8 @@ used.</dd> application uses code and resources from an example library project called TicTacToeLib.</p> <p>To download the sample applications and run them as projects in - your environment, use the <em>Android SDK and AVD Manager</em> to download the "Samples for - SDK API 8" (or later) component into your SDK.</p> + your environment, use the <em>Android SDK Manager</em> to download the "Samples for + SDK API 8" (or later) package into your SDK.</p> <p>For more information and to browse the code of the samples, see the <a href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain @@ -227,8 +227,8 @@ used.</dd> <p class="note"><strong>Note:</strong> You need SDK Tools r14 or newer to use the new library project feature that generates each library project into its own JAR file. You can download the tools and platforms using the - <em>Android SDK and AVD Manager</em>, as described in - <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> + <em>Android SDK Manager</em>, as described in + <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</p> <p>If you have source code and resources that are common to multiple Android projects, you can move them to a library project so that it is easier to maintain across applications and diff --git a/docs/html/guide/developing/testing/testing_otheride.jd b/docs/html/guide/developing/testing/testing_otheride.jd index 93af979..7745ae7 100644 --- a/docs/html/guide/developing/testing/testing_otheride.jd +++ b/docs/html/guide/developing/testing/testing_otheride.jd @@ -209,7 +209,7 @@ $ android create test-project -m ../HelloAndroid -n HelloAndroidTest -p HelloAnd <p> To update a test project with the <code>android</code> tool, enter: </p> -<pre>android update-test-project -m <main_path> -p <test_path></pre> +<pre>android update test-project -m <main_path> -p <test_path></pre> <table> <tr> diff --git a/docs/html/guide/developing/tools/adt.jd b/docs/html/guide/developing/tools/adt.jd index e48a5ae..d473e85 100644 --- a/docs/html/guide/developing/tools/adt.jd +++ b/docs/html/guide/developing/tools/adt.jd @@ -102,9 +102,8 @@ Project site.</p> (<strong>Window > Open Perspective > Traceview</strong>). </li> <li><a href="{@docRoot}guide/developing/tools/android.html">android</a>: Provides access to - the Android SDK and AVD Manager. Other <code>android</code> features such as creating or - updating projects (application and library) are integrated throughout the Eclipse IDE - (<strong>Window > Android SDK and AVD Manager</strong>). </li> + the Android SDK Manager and AVD Manager. Other <code>android</code> features such as creating or + updating projects (application and library) are integrated throughout the Eclipse IDE. </li> <li><a href="{@docRoot}guide/developing/debugging/debugging-ui.html#HierarchyViewer">Hierarchy Viewer</a>: Allows you to visualize your application's view hierarchy to find inefficiencies diff --git a/docs/html/guide/developing/tools/android.jd b/docs/html/guide/developing/tools/android.jd index a67012f..295a720 100644 --- a/docs/html/guide/developing/tools/android.jd +++ b/docs/html/guide/developing/tools/android.jd @@ -15,9 +15,16 @@ Line</a>.</li> the Command Line</a>.</li> <li>Update your Android SDK with new platforms, add-ons, and documentation. See <a href= - "{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</li> + "{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</li> </ul>If you are using Eclipse, the <code>android</code> tool's features are integrated into ADT, so you should not need to use this tool directly. + + <p class="note"><strong>Note:</strong> The documentation of options below is not exhaustive +and may be out of date. For the most current list of options, execute <code>android +--help</code>.</p> + + + <h2>Syntax</h2> <pre>android [global options] action [action options]</pre> @@ -52,6 +59,26 @@ Line</a>.</li> </tr> <tr> + <td rowspan="6"><code>avd</code></td> + + <td>None</td> + + <td>Launch the AVD Manager</td> + + <td></td> + </tr> + + <tr> + <td rowspan="6"><code>sdk</code></td> + + <td>None</td> + + <td>Launch the Android SDK Manager</td> + + <td></td> + </tr> + + <tr> <td rowspan="6"><code>create avd</code></td> <td><code>-n <name></code></td> diff --git a/docs/html/guide/developing/tools/emulator.jd b/docs/html/guide/developing/tools/emulator.jd index 5151ec1..21d4263 100644 --- a/docs/html/guide/developing/tools/emulator.jd +++ b/docs/html/guide/developing/tools/emulator.jd @@ -8,8 +8,8 @@ parent.link=index.html <h2>In this document</h2> <ol> - <li><a href="#startup-options">Emulator Startup Options</a></li> - <li><a href="#KeyMapping">Emulator Keyboard Mapping</a></li> + <li><a href="#KeyMapping">Keyboard Commands</a></li> + <li><a href="#startup-options">Command Line Parameters</a></li> </ol> <h2>See also</h2> @@ -22,30 +22,123 @@ parent.link=index.html </div> -<p>The Android SDK includes a mobile device emulator — a virtual mobile device +<p>The Android SDK includes a mobile device emulator — a virtual mobile device that runs on your computer. The emulator lets you develop and test Android applications without using a physical device.</p> -<p>When the emulator is running, you can interact with the emulated mobile -device just as you would an actual mobile device, except that you use your mouse -pointer to "touch" the touchscreen and can use some keyboard keys to -invoke certain keys on the device. </p> - -<p>This document is a reference to the available command line options and the keyboard mapping to device keys. -For a complete guide to using the Android Emulator, see +<p>This document is a reference to the available command line options and the keyboard mapping to +device keys. +For a complete guide to using the Android Emulator, see <a href="{@docRoot}guide/developing/devices/emulator.html">Using the Android Emulator</a>. -<h2 id="startup-options">Emulator Startup Options</h2> +<h2 id="KeyMapping">Keyboard Commands</h2> -<p>The emulator supports a variety of options that you can specify -when launching the emulator, to control its appearance or behavior. -Here's the command-line usage for launching the emulator with options: </p> +<p>Table 1 summarizes the mappings between the emulator keys and the keys of your keyboard.</p> + +<p class="table-caption"><strong>Table 1.</strong> Emulator keyboard mapping</p> +<table border="0" style="clear:left;"> + <tr> + <th>Emulated Device Key </th> + <th>Keyboard Key </th> + </tr> + <tr> + <td>Home</td> + <td>HOME</td> + </tr> + <tr> + <td>Menu (left softkey)</td> + <td>F2 <em>or</em> Page-up button</td> + </tr> + <tr> + <td>Star (right softkey)</td> + <td>Shift-F2 <em>or </em>Page Down</td> + </tr> + <tr> + <td>Back</td> + <td>ESC</td> + </tr> + <tr> + <td>Call/dial button </td> + <td>F3</td> + </tr> + <tr> + <td>Hangup/end call button</td> + <td>F4</td> + </tr> + <tr> + <td>Search</td> + <td>F5 </td> + </tr> + <tr> + <td>Power button</td> + <td>F7 </td> + </tr> + <tr> + <td>Audio volume up button</td> + <td>KEYPAD_PLUS, Ctrl-F5</td> + </tr> + + <tr> + <td>Audio volume down button</td> + <td>KEYPAD_MINUS, Ctrl-F6</td> + </tr> + <tr> + <td>Camera button</td> + <td>Ctrl-KEYPAD_5, Ctrl-F3</td> + </tr> + <tr> + <td>Switch to previous layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_7, Ctrl-F11</td> + </tr> + <tr> + <td>Switch to next layout orientation (for example, portrait, landscape)</td> + <td>KEYPAD_9, Ctrl-F12</td> + </tr> + <tr> + <td>Toggle cell networking on/off</td> + <td>F8</td> + </tr> + <tr> + <td>Toggle code profiling</td> + <td>F9 (only with <code>-trace</code> startup option)</td> + </tr> + <tr> + <td>Toggle fullscreen mode</td> + <td>Alt-Enter</td> + </tr> + <tr> + <td>Toggle trackball mode</td> + <td>F6</td> + </tr> + <tr> + <td>Enter trackball mode temporarily (while key is pressed)</td> + <td>Delete</td> + </tr> + <tr> + <td>DPad left/up/right/down</td> + <td>KEYPAD_4/8/6/2</td> + </tr> + <tr> + <td>DPad center click</td> + <td>KEYPAD_5</td> + </tr> + <tr> + <td>Onion alpha increase/decrease</td> + <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> + </tr> +</table> -<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> -<p class="table-caption"><strong>Table 1.</strong>Emulator startup options</p> +<h2 id="startup-options">Command Line Parameters</h2> +<p>The emulator supports a variety of options that you can specify +when launching the emulator, to control its appearance or behavior. +Here's the command-line syntax of the options available to the {@code emulator} program:</p> + +<pre>emulator -avd <avd_name> [-<option> [<value>]] ... [-<qemu args>]</pre> + +<p class="table-caption"><strong>Table 2.</strong> Emulator command line parameters</p> <table> <tr> <th width="10%" >Category</th> @@ -55,106 +148,55 @@ Here's the command-line usage for launching the emulator with options: </p> </tr> <tr> - <td rowspan="9">Help</td> - <td><code>-help</code></td> - <td>Print a list of all emulator options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-all</code></td> - <td>Print help for all startup options.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-<option></code></td> - <td>Print help for a specific startup option.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-debug-tags</code></td> - <td>Print a list of all tags for <code>-debug <tags></code>.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-disk-images</code></td> - <td>Print help for using emulator disk images.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-environment</code></td> - <td>Print help for emulator environment variables.</td> - <td> </td> -</tr><tr> - <td><code>-help-keys</code></td> - <td>Print the current mapping of keys.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-keyset-file</code></td> - <td>Print help for defining a custom key mappings file.</td> - <td> </td> -</tr> -<tr> - <td><code>-help-virtual-device</code></td> - <td>Print help for Android Virtual Device usage.</td> - <td> </td> -</tr> -<tr> <td>AVD</td> <td><code>-avd <avd_name></code> or <br> <code>@<avd_name></code></td> <td><strong>Required</strong>. Specifies the AVD to load for this emulator instance.</td> <td>You must create an AVD configuration before launching the emulator. For - information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> - Managing AVDs with AVD Manager</a>.</td> + information, see <a href="{@docRoot}guide/developing/devices/managing-avds.html">Managing + AVDs with AVD Manager</a>.</td> <tr> <td rowspan="7">Disk Images</td> <td><code>-cache <filepath></code></td> <td>Use <filepath> as the working cache partition image. </td> - <td>Optionally, you can specify a path relative to the current working directory. + <td>An absolute or relative path to the current working directory. If no cache file is specified, the emulator's default behavior is to use a temporary file instead. <p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td></tr> <tr> <td><code>-data <filepath></code></td> - <td>Use <filepath> as the working user-data disk image. </td> - <td>Optionally, you can specify a path relative to the current working directory. - If <code>-data</code> is not used, the emulator looks for a file named "userdata-qemu.img" - in the storage area of the AVD being used (see <code>-avd</code>). + <td>Use {@code <filepath>} as the working user-data disk image. </td> + <td>Optionally, you can specify a path relative to the current working directory. + If <code>-data</code> is not used, the emulator looks for a file named {@code userdata-qemu.img} + in the storage area of the AVD being used (see <code>-avd</code>). </td></tr> <!-- <tr> <td><code>-datadir <dir></code></td> <td>Search for the user-data disk image specified in <code>-data</code> in <dir></td> - <td><code><dir></code> is a path relative to the current working directory. + <td><code><dir></code> is a path relative to the current working directory. -<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image -in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information +<p>If you do not specify <code>-datadir</code>, the emulator looks for the user-data image +in the storage area of the AVD being used (see <code>-avd</code>)</p><p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td></tr> --> -<!-- +<!-- <tr> <td><code>-image <filepath></code></td> <td>Use <filepath> as the system image.</td> - <td>Optionally, you can specify a path relative to the current working directory. + <td>Optionally, you can specify a path relative to the current working directory. Default is <system>/system.img.</td> </tr> --> <tr> <td><code>-initdata <filepath></code></td> - <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents + <td>When resetting the user-data image (through <code>-wipe-data</code>), copy the contents of this file to the new user-data disk image. By default, the emulator copies the <code><system>/userdata.img</code>.</td> - <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> -</tr> -<!-- -<tr> - <td><code>-kernel <filepath></code></td> - <td>Use <filepath> as the emulated kernel.</td> - <td>Optionally, you can specify a path relative to the current working directory. </td> + <td>Optionally, you can specify a path relative to the current working directory. See also <code>-wipe-data</code>. + <p>For more information on disk images, use <code>-help-disk-images</code>.</p></td> </tr> ---> <tr> <td><code>-nocache</code></td> <td>Start the emulator without a cache partition.</td> @@ -163,8 +205,9 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-ramdisk <filepath></code></td> <td>Use <filepath> as the ramdisk image.</td> - <td>Default value is <code><system>/ramdisk.img</code>. - <p>Optionally, you can specify a path relative to the current working directory. For more information on disk images, use <code>-help-disk-images</code>.</p> + <td>Default value is <code><system>/ramdisk.img</code>. + <p>Optionally, you can specify a path relative to the current working directory. + For more information on disk images, use <code>-help-disk-images</code>.</p> </td> </tr> <tr> @@ -178,17 +221,17 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-system <dirpath></code></td> <td>Search for system, ramdisk and user data images in <dir>.</td> - <td><code><dir></code> is a directory path relative to the current + <td><code><dir></code> is a directory path relative to the current working directory.</td> </tr> --> <tr> <td><code>-wipe-data</code></td> - <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and - <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, - then copies the contents of the file at <code>-inidata</code> data to the image file before starting. + <td>Reset the current user-data disk image (that is, the file specified by <code>-datadir</code> and + <code>-data</code>, or the default file). The emulator deletes all data from the user data image file, + then copies the contents of the file at <code>-inidata</code> data to the image file before starting. </td> - <td>See also <code>-initdata</code>. + <td>See also <code>-initdata</code>. <p>For more information on disk images, use <code>-help-disk-images</code>.</p> </td> </tr> @@ -196,7 +239,7 @@ on disk images, use <code>-help-disk-images</code>.</p> <td rowspan="9">Debug</td> <td><code>-debug <tags></code></td> <td>Enable/disable debug messages for the specified debug tags.</td> - <td><code><tags></code> is a space/comma/column-separated list of debug component names. + <td><code><tags></code> is a space/comma/column-separated list of debug component names. Use <code>-help-debug-tags</code> to print a list of debug component names that you can use. </td> </tr> <tr> @@ -217,16 +260,16 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-shell</code></td> <td>Create a root shell console on the current terminal.</td> - <td>You can use this command even if the adb daemon in the emulated system is broken. + <td>You can use this command even if the adb daemon in the emulated system is broken. Pressing Ctrl-c from the shell stops the emulator instead of the shell.</td> </tr> <tr> <td><code>-shell-serial <device></code></td> - <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character + <td>Enable the root shell (as in <code>-shell</code> and specify the QEMU character device to use for communication with the shell.</td> - <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at - <a href="http://wiki.qemu.org/download/qemu-doc.html">wiki.qemu.org</a> - for more information.</p> + <td><device> must be a QEMU device type. See the documentation for '-serial <em>dev</em>' at + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a> + for a list of device types. <p>Here are some examples: </p> <ul> @@ -250,11 +293,11 @@ on disk images, use <code>-help-disk-images</code>.</p> <tr> <td><code>-verbose</code></td> <td>Enable verbose output.</td> - <td>Equivalent to <code>-debug-init</code>. -<p>You can define the default verbose output options used by emulator instances in the Android environment variable -ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: + <td>Equivalent to <code>-debug-init</code>. +<p>You can define the default verbose output options used by emulator instances in the Android environment variable +ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, specifying only the stem of each option: <code>-debug-<tags>.</code> </p> -<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: +<p>Here's an example showing ANDROID_VERBOSE defined with the <code>-debug-init</code> and <code>-debug-modem</code> options: <p><code>ANDROID_VERBOSE=init,modem</code></p> <p>For more information about debug tags, use <code><-help-debug-tags></code>.</p> </td> @@ -316,8 +359,9 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <tr> <td><code>-netdelay <delay></code></td> <td>Set network latency emulation to <delay>.</td> - <td>Default value is <code>none</code>. See the table in <a href="#netdelay">Network Delay Emulation</a> for - supported <code><delay></code> values. </td> + <td>Default value is <code>none</code>. See the table in + <a href="{@docRoot}guide/developing/devices/emulator.html#netdelay">Network Delay Emulation</a> + for supported <code><delay></code> values. </td> </tr> <tr> <td><code>-netfast</code></td> @@ -326,18 +370,19 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <tr> <td><code>-netspeed <speed></code></td> <td>Set network speed emulation to <speed>.</td> - <td>Default value is <code>full</code>. See the table in <a href="#netspeed">Network Speed Emulation</a> for + <td>Default value is <code>full</code>. See the table in + <a href="{@docRoot}guide/developing/devices/emulator.html#netspeed">Network Speed Emulation</a> for supported <code><speed></code> values. </td> </tr> <tr> <td><code>-port <port></code></td> <td>Set the console port number for this emulator instance to <code><port></code>.</td> - <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 + <td>The console port number must be an even integer between 5554 and 5584, inclusive. <code><port></code>+1 must also be free and will be reserved for ADB.</td> </tr> <tr> <td><code>-report-console <socket></code></td> - <td>Report the assigned console port for this emulator instance to a remote third party + <td>Report the assigned console port for this emulator instance to a remote third party before starting the emulation. </td> <td><code><socket></code> must use one of these formats: @@ -347,14 +392,14 @@ ANDROID_VERBOSE. Define the options you want to use in a comma-delimited list, s <p>Use <code>-help-report-console</code></p> to view more information about this topic. </td> </tr> <tr> - <td rowspan="8">System</td> + <td rowspan="10">System</td> <td><code>-cpu-delay <delay></code></td> <td>Slow down emulated CPU speed by <delay> </td> <td>Supported values for <delay> are integers between 0 and 1000. -<p>Note that the <delay> does not correlate to clock speed or other absolute metrics -— it simply represents an abstract, relative delay factor applied non-deterministically -in the emulator. Effective performance does not always +<p>Note that the <delay> does not correlate to clock speed or other absolute metrics +— it simply represents an abstract, relative delay factor applied non-deterministically +in the emulator. Effective performance does not always scale in direct relationship with <delay> values.</p> </td> </tr> @@ -362,9 +407,9 @@ scale in direct relationship with <delay> values.</p> <td><code>-gps <device></code></td> <td>Redirect NMEA GPS to character device.</td> <td>Use this command to emulate an NMEA-compatible GPS unit connected to - an external character device or socket. The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at - <a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. + an external character device or socket. The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at + <a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> @@ -372,18 +417,37 @@ scale in direct relationship with <delay> values.</p> <td>Disable JNI checks in the Dalvik runtime.</td><td> </td></tr> <tr> <td><code>-qemu</code></td> - <td>Pass arguments to qemu.</td> - <td> </td></tr> + <td>Pass arguments to the qemu emulator software.</td> + <td><p class="caution"><strong>Important:</strong> When using this option, make sure it is the + <em>last option</em> specified, since all options after it are interpretted as qemu-specific + options.</p></td></tr> +<tr> + <td><code>-qemu -enable-kvm</code></td> + <td>Enable KVM acceleration of the emulator virtual machine.</td> + <td>This option is only effective when your system is set up to use + <a href="{@docRoot}guide/developing/devices/emulator.html#vm-linux">KVM-based VM acceleration</a>. + You can optionally specify a memory size ({@code -m <size>}) for the VM, which should match + your emulator's memory size:</p> + {@code -qemu -m 512 -enable-kvm}<br> + {@code -qemu -m 1024 -enable-kvm} + </td></tr> <tr> <td><code>-qemu -h</code></td> <td>Display qemu help.</td> <td></td></tr> <tr> + <td><code>-gpu on</code></td> + <td>Turn on graphics acceleration for the emulator.</td> + <td>This option is only available for emulators using a system image with API Level 15, revision 3 + and higher. For more information, see + <a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">Using the Android + Emulator</a>.</td></tr> +<tr> <td><code>-radio <device></code></td> <td>Redirect radio mode to the specified character device.</td> - <td>The format of <code><device></code> must be QEMU-specific - serial device specification. See the documentation for 'serial -dev' at -<a href="http://www.bellard.org/qemu/qemu-doc.html#SEC10">http://www.bellard.org/qemu/qemu-doc.html#SEC10</a>. + <td>The format of <code><device></code> must be QEMU-specific + serial device specification. See the documentation for 'serial -dev' at +<a href="http://wiki.qemu.org/download/qemu-doc.html">http://wiki.qemu.org/download/qemu-doc.html</a>. </td> </tr> <tr> @@ -419,8 +483,8 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-scale <scale></code></td> <td>Scale the emulator window. </td> - <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can - also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" + <td><code><scale></code> is a number between 0.1 and 3 that represents the desired scaling factor. You can + also specify scale as a DPI value if you add the suffix "dpi" to the scale value. A value of "auto" tells the emulator to select the best window size.</td> </tr> <tr> @@ -434,7 +498,7 @@ scale in direct relationship with <delay> values.</p> <tr> <td><code>-keyset <file></code></td> <td>Use the specified keyset file instead of the default.</td> - <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. + <td>The keyset file defines the list of key bindings between the emulator and the host keyboard. For more information, use <code>-help-keyset</code> to print information about this topic. </td> </tr> @@ -460,113 +524,58 @@ option. Using this option may yield unexpected and in some cases misleading results, since the density with which to render the skin may not be defined. AVDs let you associate each skin with a default density and override the default as needed. For more information, see <a -href="{@docRoot}guide/developing/devices/managing-avds.html#createavd"> -Managing Virtual Devices with AVD Manager</a>. +href="{@docRoot}guide/developing/devices/managing-avds.html">Managing Virtual Devices +with AVD Manager</a>. </td> </tr> <tr> <td><code>-skindir <dir></code></td> <td>This emulator option is deprecated. </td> - <td>See comments for <code>-skin</code>, above.</td></tr> -</table> - - - -<h2 id="KeyMapping">Emulator Keyboard Mapping</h2> - -<p>The table below summarizes the mappings between the emulator keys and and -the keys of your keyboard. </p> -<p class="table-caption"><strong>Table 2.</strong> Emulator keyboard mapping</p> -<table border="0" style="clear:left;"> - <tr> - <th>Emulated Device Key </th> - <th>Keyboard Key </th> - </tr> - <tr> - <td>Home</td> - <td>HOME</td> - </tr> - <tr> - <td>Menu (left softkey)</td> - <td>F2 <em>or</em> Page-up button</td> - </tr> - <tr> - <td>Star (right softkey)</td> - <td>Shift-F2 <em>or </em>Page Down</td> - </tr> - <tr> - <td>Back</td> - <td>ESC</td> - </tr> - <tr> - <td>Call/dial button </td> - <td>F3</td> - </tr> - <tr> - <td>Hangup/end call button</td> - <td>F4</td> - </tr> - <tr> - <td>Search</td> - <td>F5 </td> - </tr> - <tr> - <td>Power button</td> - <td>F7 </td> - </tr> - <tr> - <td>Audio volume up button</td> - <td>KEYPAD_PLUS, Ctrl-5</td> - </tr> - - <tr> - <td>Audio volume down button</td> - <td>KEYPAD_MINUS, Ctrl-F6</td> - </tr> - <tr> - <td>Camera button</td> - <td>Ctrl-KEYPAD_5, Ctrl-F3</td> - </tr> - <tr> - <td>Switch to previous layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_7, Ctrl-F11</td> - </tr> - <tr> - <td>Switch to next layout orientation (for example, portrait, landscape)</td> - <td>KEYPAD_9, Ctrl-F12</td> - </tr> - <tr> - <td>Toggle cell networking on/off</td> - <td>F8</td> - </tr> - <tr> - <td>Toggle code profiling</td> - <td>F9 (only with <code>-trace</code> startup option)</td> - </tr> - <tr> - <td>Toggle fullscreen mode</td> - <td>Alt-Enter</td> - </tr> - <tr> - <td>Toggle trackball mode</td> - <td>F6</td> - </tr> - <tr> - <td>Enter trackball mode temporarily (while key is pressed)</td> - <td>Delete</td> - </tr> - <tr> - <td>DPad left/up/right/down</td> - <td>KEYPAD_4/8/6/2</td> - </tr> - <tr> - <td>DPad center click</td> - <td>KEYPAD_5</td> - </tr> - <tr> - <td>Onion alpha increase/decrease</td> - <td>KEYPAD_MULTIPLY(*) / KEYPAD_DIVIDE(/)</td> - </tr> + <td>See comments for <code>-skin</code>, above.</td> +</tr> +<tr> + <td rowspan="9">Help</td> + <td><code>-help</code></td> + <td>Print a list of all emulator options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-all</code></td> + <td>Print help for all startup options.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-<option></code></td> + <td>Print help for a specific startup option.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-debug-tags</code></td> + <td>Print a list of all tags for <code>-debug <tags></code>.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-disk-images</code></td> + <td>Print help for using emulator disk images.</td> + <td> </td> + </tr> +<tr> + <td><code>-help-environment</code></td> + <td>Print help for emulator environment variables.</td> + <td> </td>s +</tr><tr> + <td><code>-help-keys</code></td> + <td>Print the current mapping of keys.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-keyset-file</code></td> + <td>Print help for defining a custom key mappings file.</td> + <td> </td> +</tr> +<tr> + <td><code>-help-virtual-device</code></td> + <td>Print help for Android Virtual Device usage.</td> + <td> </td> +</tr> </table> - -<p>Note that, to use keypad keys, you must first disable NumLock on your development computer. </p> diff --git a/docs/html/guide/developing/tools/index.jd b/docs/html/guide/developing/tools/index.jd index 3d831f3..5e9f686 100644 --- a/docs/html/guide/developing/tools/index.jd +++ b/docs/html/guide/developing/tools/index.jd @@ -12,8 +12,8 @@ latest Android platform.</p> <h2 id="tools-sdk">SDK Tools</h2> <p>The SDK tools are installed with the SDK starter package and are periodically updated. The SDK tools are required if you are developing Android applications. The most important SDK tools -include the Android SDK and AVD Manager (<code>android</code>), the emulator -(<code>emulator</code>), and the Dalvik Debug Monitor Server +include the Android SDK Manager (<code>android sdk</code>), the AVD Manager (<code>android +avd</code>) the emulator (<code>emulator</code>), and the Dalvik Debug Monitor Server (<code>ddms</code>). A short summary of some frequently-used SDK tools is provided below.</p> <dl> diff --git a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd index 499b610..346a0c6 100644 --- a/docs/html/guide/developing/tools/monkeyrunner_concepts.jd +++ b/docs/html/guide/developing/tools/monkeyrunner_concepts.jd @@ -236,7 +236,7 @@ Table 1 explains the flags and arguments. You can generate an API reference for monkeyrunner by running: </p> <pre> -monkeyrunner <format> help.py <outfile> +monkeyrunner help.py <format> <outfile> </pre> <p> The arguments are: diff --git a/docs/html/guide/developing/tools/proguard.jd b/docs/html/guide/developing/tools/proguard.jd index eca262a..ea8a1ea 100644 --- a/docs/html/guide/developing/tools/proguard.jd +++ b/docs/html/guide/developing/tools/proguard.jd @@ -39,7 +39,7 @@ parent.link=index.html sized <code>.apk</code> file that is more difficult to reverse engineer. Because ProGuard makes your application harder to reverse engineer, it is important that you use it when your application utilizes features that are sensitive to security like when you are - <a href="{@docRoot}guide/publishing/licensing.html">Licensing Your Applications</a>.</p> + <a href="{@docRoot}guide/market/licensing/index.html">Licensing Your Applications</a>.</p> <p>ProGuard is integrated into the Android build system, so you do not have to invoke it manually. ProGuard runs only when you build your application in release mode, so you do not diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 4a9a684..62d18ae 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -90,21 +90,20 @@ <ul> <li> <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-basics.html"> - <span class="en">Content Provider Basics</span> + <span class="en">Content Provider Basics<span +class="new"> new!</span></span> </a> - <span class="new">new!</span> </li> <li> <a href="<?cs var:toroot ?>guide/topics/providers/content-provider-creating.html"> - <span class="en">Creating a Content Provider</span> + <span class="en">Creating a Content Provider<span +class="new"> new!</span></span> </a> - <span class="new">new!</span> </li> <li> <a href="<?cs var:toroot ?>guide/topics/providers/calendar-provider.html"> - <span class="en">Calendar Provider</span> + <span class="en">Calendar Provider<span class="new"> new!</span></span> </a> - <span class="new">new!</span> </li> </ul> </li> @@ -130,8 +129,8 @@ <span class="en">Input Events</span> </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/menus.html"> - <span class="en">Menus</span> - </a> <span class="new">updated</span></li> + <span class="en">Menus<span class="new"> new!</span></span> + </a></li> <li><a href="<?cs var:toroot ?>guide/topics/ui/actionbar.html"> <span class="en">Action Bar</span> </a></li> @@ -160,6 +159,19 @@ <li><a href="<?cs var:toroot ?>guide/topics/ui/custom-components.html"> <span class="en">Custom Components</span> </a></li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/index.html"> + <span class="en">Accessibility<span class="new"> new!</span></span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/apps.html"> + <span class="en">Making Applications Accessible</span> + </a></li> + <li><a href="<?cs var:toroot ?>guide/topics/ui/accessibility/services.html"> + <span class="en">Building Accessibility Services</span> + </a></li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/topics/ui/binding.html"> <span class="en">Binding to Data with AdapterView</span> </a></li> @@ -259,13 +271,13 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/graphics/index.html"> <span class="en">Graphics</span> - </a> <span class="new-child">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/graphics/2d-graphics.html"> <span class="en">Canvas and Drawables</span></a></li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/hardware-accel.html"> <span class="en">Hardware Acceleration</span></a> - <span class="new">new!</span></li> + </li> <li><a href="<?cs var:toroot ?>guide/topics/graphics/opengl.html"> <span class="en">OpenGL</span> </a></li> @@ -287,7 +299,6 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/renderscript/index.html"> <span class="en">Renderscript</span></a> - <span class="new">updated</span> </div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/renderscript/graphics.html"> @@ -318,7 +329,6 @@ </li> <li><a href="<?cs var:toroot ?>guide/topics/media/camera.html"> <span class="en">Camera</span></a> - <span class="new">new!</span> </li> <li><a href="<?cs var:toroot ?>guide/topics/media/audio-capture.html"> <span class="en">Audio Capture</span></a> @@ -332,7 +342,7 @@ <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/topics/sensors/index.html"> <span class="en">Sensors</span> - </a> <span class="new">new!</span></div> + </a></div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/sensors/sensors_overview.html"> <span class="en">Sensors Overview</span> @@ -373,7 +383,7 @@ </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/topics/nfc/index.html"> - <span class="en">Near Field Communication</span></a> <span class="new">updated</span> + <span class="en">Near Field Communication</span></a> </div> <ul> <li><a href="<?cs var:toroot ?>guide/topics/nfc/nfc.html">NFC Basics</a></li> @@ -381,7 +391,7 @@ </ul> </li> <li><a href="<?cs var:toroot?>guide/topics/wireless/wifip2p.html"> - <span class="en">Wi-Fi Direct</span></a> <span class="new">new!</span> + <span class="en">Wi-Fi Direct</span></a> </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/topics/usb/index.html"> @@ -444,15 +454,31 @@ </li> <li> - <span class="heading"> - <span class="en">Android Market Topics</span> - </span> + <h2> + <span class="en">Google Play Topics</span> + </h2> <ul> <li><a href="<?cs var:toroot ?>guide/publishing/publishing.html"> - <span class="en">Publishing on Android Market</span> + <span class="en">Publishing on Google Play</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/publishing/licensing.html"> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/market/licensing/index.html"> <span class="en">Application Licensing</span></a> + </div> + <ul> + <li><a href="<?cs var:toroot?>guide/market/licensing/overview.html"> + <span class="en">Licensing Overview</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/setting-up.html"> + <span class="en">Setting Up for Licensing</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/adding-licensing.html"> + <span class="en">Adding Licensing to Your App</span></a> + </li> + <li><a href="<?cs var:toroot?>guide/market/licensing/licensing-reference.html"> + <span class="en">Licensing Reference</span></a> + </li> + </ul> </li> <li class="toggle-list"> <div><a href="<?cs var:toroot?>guide/market/billing/index.html"> @@ -480,11 +506,14 @@ </ul> </li> <li><a href="<?cs var:toroot ?>guide/appendix/market-filters.html"> - <span class="en">Market Filters</span></a> + <span class="en">Filters on Google Play</span></a> </li> <li><a href="<?cs var:toroot ?>guide/market/publishing/multiple-apks.html"> <span class="en">Multiple APK Support</span></a> </li> + <li><a href="<?cs var:toroot ?>guide/market/expansion-files.html"> + <span class="en">APK Expansion Files<span class="new"> new!</span></span></a> + </li> </ul> </li> @@ -768,7 +797,7 @@ applications</span> </li> <li><a href="<?cs var:toroot ?>guide/practices/tablets-and-handsets.html"> <span class="en">Supporting Tablets and Handsets</span> - </a> <span class="new">new!</span></li> + </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/index.html"> <span class="en">UI Guidelines</span> @@ -805,19 +834,10 @@ applications</span> <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/widget_design.html"> <span class="en">App Widget Design</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/activity_task_design.html"> - <span class="en">Activity and Task Design</span> - </a></li> - <li><a href="<?cs var:toroot ?>guide/practices/ui_guidelines/menu_design.html"> - <span class="en">Menu Design</span> - </a></li> </ul> </li> </ul> <ul> - <li><a href="<?cs var:toroot ?>guide/practices/design/accessibility.html"> - <span class="en">Designing for Accessibility</span> - </a></li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>guide/practices/design/performance.html"> <span class="en">Designing for Performance</span> diff --git a/docs/html/guide/index.jd b/docs/html/guide/index.jd index 38f71c0..8378472 100644 --- a/docs/html/guide/index.jd +++ b/docs/html/guide/index.jd @@ -34,9 +34,9 @@ Fundamentals</a>. Then explore other topics — from designing a user interface and setting up resources to storing data and using permissions — as needed.</dd> -<dt><b>Android Market Topics</b></dt> -<dd>Documentation for topics that concern publishing and monetizing applications on Android -Market, such as how to enforce licensing policies and implement in-app billing.</dd> +<dt><b>Google Play Topics</b></dt> +<dd>Documentation for topics that concern publishing and monetizing applications on Google Play, +such as how to enforce licensing policies and implement in-app billing.</dd> <dt><b>Developing</b></dt> <dd>Directions for using Android's development and debugging tools, diff --git a/docs/html/guide/market/billing/billing_admin.jd b/docs/html/guide/market/billing/billing_admin.jd index a84eb4e..0f869ab 100755 --- a/docs/html/guide/market/billing/billing_admin.jd +++ b/docs/html/guide/market/billing/billing_admin.jd @@ -38,19 +38,19 @@ parent.link=index.html few administrative tasks, including setting up and maintaining your product list on the publisher site, registering test accounts, and handling refunds when necessary.</p> -<p>You must have an Android Market publisher account to register test accounts. And you must have a +<p>You must have a Google Play publisher account to register test accounts. And you must have a Google Checkout merchant account to create a product list and issue refunds to your users. If you -already have a publisher account on Android Market, you can use your existing account. You do not +already have a publisher account on Google Play, you can use your existing account. You do not need to register for a new account to support in-app billing. If you do not have a publisher -account, you can register as an Android Market developer and set up a publisher account at the -Android Market <a href="http://market.android.com/publish">publisher site</a>. If you do not have a +account, you can register as a Google Play developer and set up a publisher account at the +Google Play <a href="http://play.google.com/apps/publish">publisher site</a>. If you do not have a Google Checkout merchant account, you can register for one at the <a href="http://checkout.google.com">Google Checkout site</a>.</p> <h2 id="billing-list-setup">Creating a Product List</h2> -<p>The Android Market publisher site provides a product list for each of your published -applications. You can sell an item using Android Market's in-app billing feature only if the item is +<p>The Google Play publisher site provides a product list for each of your published +applications. You can sell an item using Google Play's in-app billing feature only if the item is listed on an application's product list. Each application has its own product list; you cannot sell items that are listed in another application's product list.</p> @@ -77,7 +77,7 @@ storing and delivering the digital content that you sell in your applications.</ </p> <p>You can create a product list for any published application or any draft application that's been -uploaded and saved to the Android Market site. However, you must have a Google Checkout merchant +uploaded and saved to the Google Play site. However, you must have a Google Checkout merchant account and the application's manifest must include the <code>com.android.vending.BILLING</code> permission. If an application's manifest does not include this permission, you will be able to edit existing items in the product list but you will not be able to add new items to the list. For more @@ -104,8 +104,8 @@ number of in-app items.</p> <p>To add an item to a product list using the In-app Products UI, follow these steps:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> - <li>In the <strong>All Android Market listings</strong> panel, under the application name, click + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> + <li>In the <strong>All Google Play listings</strong> panel, under the application name, click <strong>In-app Products</strong>.</li> <li>On the In-app Products List page, click <strong>Add in-app product</strong>.</li> <li>On the Create New In-app Product page (see figure 3), provide details about the item you are @@ -137,7 +137,7 @@ number of in-app items.</p> <li><strong>Publishing State</strong> <p>An item's publishing state can be <strong>Published</strong> or <strong>Unpublished </strong>. To be visible to a user during checkout, an item's publishing state must be set to - <strong>Published</strong> and the item's application must be published on Android Market.</p> + <strong>Published</strong> and the item's application must be published on Google Play.</p> <p class="note"><strong>Note:</strong> This is not true for test accounts. An item is visible to a test account if the application is not published and the item is published. See <a href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-real">Testing In-app @@ -167,9 +167,9 @@ number of in-app items.</p> <p>You must provide a default price in your home currency. You can also provide prices in other currencies, but you can do this only if a currency's corresponding country is listed as a target country for your application. You can specify target countries on the Edit Application - page in the Android Market developer console.</p> + page in the Google Play developer console.</p> <p>To specify prices in other currencies, you can manually enter the price for each - currency or you can click <strong>Auto Fill</strong> and let Android Market do a one-time + currency or you can click <strong>Auto Fill</strong> and let Google Play do a one-time conversion from your home currency to the currencies you are targeting (see figure 4).</p> </li> </ul> @@ -357,8 +357,8 @@ with the <em>locale</em> field.</p> <p>To import the items that are specified in your CSV file, do the following:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> - <li>In the <strong>All Android Market listings</strong> panel, under the application name, click + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> + <li>In the <strong>All Google Play listings</strong> panel, under the application name, click <strong>In-app Products</strong>.</li> <li>On the In-app Products List page, click <strong>Choose File</strong> and select your CSV file. @@ -381,17 +381,17 @@ a product list and you want to start managing the product list through a CSV fil <h3 id="billing-purchase-type">Choosing a Purchase Type</h3> -<p>An item's purchase type controls how Android Market manages the purchase of the item. There are +<p>An item's purchase type controls how Google Play manages the purchase of the item. There are two purchase types: "managed per user account" and "unmanaged."</p> <p>Items that are managed per user account can be purchased only once per user account. When an item -is managed per user account, Android Market permanently stores the transaction information for each -item on a per-user basis. This enables you to query Android Market with the +is managed per user account, Google Play permanently stores the transaction information for each +item on a per-user basis. This enables you to query Google Play with the <code>RESTORE_TRANSACTIONS</code> request and restore the state of the items a specific user has purchased.</p> -<p>If a user attempts to purchase a managed item that has already been purchased, Android Market -displays an "Item already purchased" error. This occurs during checkout, when Android Market +<p>If a user attempts to purchase a managed item that has already been purchased, Google Play +displays an "Item already purchased" error. This occurs during checkout, when Google Play displays the price and description information on the checkout page. When the user dismisses the error message, the checkout page disappears and the user returns to your user interface. As a best practice, your application should prevent the user from seeing this error. The sample application @@ -404,10 +404,10 @@ or application features. These items are not transient and usually need to be re user reinstalls your application, wipes the data on their device, or installs your application on a new device.</p> -<p>Items that are unmanaged do not have their transaction information stored on Android Market, -which means you cannot query Android Market to retrieve transaction information for items whose +<p>Items that are unmanaged do not have their transaction information stored on Google Play, +which means you cannot query Google Play to retrieve transaction information for items whose purchase type is listed as unmanaged. You are responsible for managing the transaction information -of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Android Market +of unmanaged items. Also, unmanaged items can be purchased multiple times as far as Google Play is concerned, so it's also up to you to control how many times an unmanaged item can be purchased.</p> @@ -417,10 +417,10 @@ times.</p> <h2 id="billing-refunds">Handling Refunds</h2> -<p>In-app billing does not allow users to send a refund request to Android Market. Refunds for +<p>In-app billing does not allow users to send a refund request to Google Play. Refunds for in-app purchases must be directed to you (the application developer). You can then process the -refund through your Google Checkout merchant account. When you do this, Android Market receives a -refund notification from Google Checkout, and Android Market sends a refund message to your +refund through your Google Checkout merchant account. When you do this, Google Play receives a +refund notification from Google Checkout, and Google Play sends a refund message to your application. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a> and <a @@ -434,9 +434,9 @@ information.</p> <h2 id="billing-testing-setup">Setting Up Test Accounts</h2> -<p>The Android Market publisher site lets you set up one or more test accounts. A test account is a +<p>The Google Play publisher site lets you set up one or more test accounts. A test account is a regular Google account that you register on the publisher site as a test account. Test accounts are -authorized to make in-app purchases from applications that you have uploaded to the Android Market +authorized to make in-app purchases from applications that you have uploaded to the Google Play site but have not yet published.</p> <p>You can use any Google account as a test account. Test accounts are useful if you want to let @@ -458,7 +458,7 @@ accounts yourself and distribute the credentials to your developers or testers.< <p>To add test accounts to your publisher account, follow these steps:</p> <ol> - <li><a href="http://market.android.com/publish">Log in</a> to your publisher account.</li> + <li><a href="http://play.google.com/apps/publish">Log in</a> to your publisher account.</li> <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li> <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 5).</li> @@ -480,7 +480,7 @@ support resources listed in the following table (see table 2). By directing your correct forum, you can get the support you need more quickly.</p> <p class="table-caption" id="support-table"><strong>Table 2.</strong> Developer support resources -for Android Market in-app billing.</p> +for Google Play in-app billing.</p> <table> @@ -502,8 +502,8 @@ href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.co android</a></td> </tr> <tr> -<td>Market billing issue tracker</td> -<td><a href="http://code.google.com/p/marketbilling/issues/">Market billing +<td>Billing issue tracker</td> +<td><a href="http://code.google.com/p/marketbilling/issues/">Billing project issue tracker</a></td> <td>Bug and issue reports related specifically to in-app billing sample code.</td> </tr> diff --git a/docs/html/guide/market/billing/billing_best_practices.jd b/docs/html/guide/market/billing/billing_best_practices.jd index d9776af..e100ce5 100755 --- a/docs/html/guide/market/billing/billing_best_practices.jd +++ b/docs/html/guide/market/billing/billing_best_practices.jd @@ -32,7 +32,7 @@ parent.link=index.html <p>As you design your in-app billing implementation, be sure to follow the security and design guidelines that are discussed in this document. These guidelines are recommended best practices for -anyone who is using Android Market's in-app billing service.</p> +anyone who is using Google Play's in-app billing service.</p> <h2>Security Best Practices</h2> @@ -92,7 +92,7 @@ replay attacks.</p> nonces on the server.</p> <h4>Take action against trademark and copyright infringement</h4> -<p>If you see your content being redistributed on Android Market, act quickly and decisively. File a +<p>If you see your content being redistributed on Google Play, act quickly and decisively. File a <a href="http://market.android.com/support/bin/answer.py?hl=en&answer=141511">trademark notice of infringement</a> or a <a href="http://www.google.com/android_dmca.html">copyright notice of infringement</a>.</p> @@ -102,7 +102,7 @@ infringement</a>.</p> purchase state of the unlocked content whenever a user accesses the content. This allows you to revoke use when necessary and minimize piracy.</p> -<h4>Protect your Android Market public key</h4> +<h4>Protect your Google Play public key</h4> <p>To keep your public key safe from malicious users and hackers, do not embed it in any code as a literal string. Instead, construct the string at runtime from pieces or use bit manipulation (for example, XOR with some other string) to hide the actual key. The key itself is not secret diff --git a/docs/html/guide/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index 6017583..4b3650f 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -35,8 +35,8 @@ parent.link=index.html </div> </div> -<p>Android Market In-app Billing provides a straightforward, simple interface for sending in-app -billing requests and managing in-app billing transactions using Android Market. This document helps +<p>In-app Billing on Google Play provides a straightforward, simple interface for sending in-app +billing requests and managing in-app billing transactions using Google Play. This document helps you implement in-app billing by stepping through the primary implementation tasks, using the in-app billing sample application as an example.</p> @@ -53,23 +53,23 @@ billing.</p> <li><a href="#billing-permission">Update your AndroidManifest.xml file</a>.</li> <li><a href="#billing-service">Create a Service</a> and bind it to the <code>MarketBillingService</code> so your application can send billing requests and receive - billing responses from the Android Market application.</li> + billing responses from Google Play.</li> <li><a href="#billing-broadcast-receiver">Create a BroadcastReceiver</a> to handle broadcast - intents from the Android Market application.</li> + intents from Google Play.</li> <li><a href="#billing-signatures">Create a security processing component</a> to verify the - integrity of the transaction messages that are sent by Android Market .</li> + integrity of the transaction messages that are sent by Google Play.</li> <li><a href="#billing-implement">Modify your application code</a> to support in-app billing.</li> </ol> <h2 id="billing-download">Downloading the Sample Application</h2> <p>The in-app billing sample application shows you how to perform several tasks that are common to -all Android Market in-app billing implementations, including:</p> +all in-app billing implementations, including:</p> <ul> - <li>Sending in-app billing requests to the Android Market application.</li> - <li>Handling synchronous responses from the Android Market application.</li> - <li>Handling broadcast intents (asynchronous responses) from the Android Market application.</li> + <li>Sending in-app billing requests to Google Play.</li> + <li>Handling synchronous responses from Google Play.</li> + <li>Handling broadcast intents (asynchronous responses) from Google Play.</li> <li>Using in-app billing security mechanisms to verify the integrity of billing responses.</li> <li>Creating a user interface that lets users select items for purchase.</li> </ul> @@ -91,8 +91,8 @@ application source files.</p> <tr> <td>IMarketBillingService.aidl</td> -<td>Android Interface Definition Library (AIDL) file that defines the IPC interface to Android -Market's in-app billing service (<code>MarketBillingService</code>).</td> +<td>Android Interface Definition Library (AIDL) file that defines the IPC interface to Google +Play's in-app billing service (<code>MarketBillingService</code>).</td> </tr> <tr> @@ -109,12 +109,12 @@ history.</td> <tr> <td>BillingReceiver.java</td> <td>A {@link android.content.BroadcastReceiver} that receives asynchronous response messages - (broadcast intents) from Android Market. Forwards all messages to the + (broadcast intents) from Google Play. Forwards all messages to the <code>BillingService</code>.</td> </tr> <tr> <td>BillingService.java</td> - <td>A {@link android.app.Service} that sends messages to Android Market on behalf of the + <td>A {@link android.app.Service} that sends messages to Google Play on behalf of the application by connecting (binding) to the <code>MarketBillingService</code>.</td> </tr> @@ -136,8 +136,8 @@ history.</td> <tr> <td>Consts.java</td> -<td>Defines various Android Market constants and sample application constants. All constants that -are defined by Android Market must be defined the same way in your application.</td> +<td>Defines various Google Play constants and sample application constants. All constants that +are defined by Google Play must be defined the same way in your application.</td> </tr> <tr> @@ -149,8 +149,8 @@ relies on these utility classes.</td> </table> <p>The in-app billing sample application is available as a downloadable component of the Android -SDK. To download the sample application component, launch the Android SDK and AVD Manager and then -select the "Google Market Billing package" component (see figure 1), and click <strong>Install +SDK. To download the sample application component, launch the Android SDK Manager and then +select the <strong>Google Market Billing package</strong> component (see figure 1), and click <strong>Install Selected</strong> to begin the download.</p> @@ -160,7 +160,7 @@ Selected</strong> to begin the download.</p> the AIDL file. </p> -<p>When the download is complete, the Android SDK and AVD Manager saves the component into the +<p>When the download is complete, the Android SDK Manager saves the component into the following directory:</p> <p><code><sdk>/extras/google/market_billing/</code></p> @@ -171,7 +171,7 @@ running the sample application involves three tasks:</p> <ul> <li>Configuring and building the sample application.</li> - <li>Uploading the sample application to Android Market.</li> + <li>Uploading the sample application to Google Play.</li> <li>Setting up test accounts and running the sample application.</li> </ul> @@ -186,12 +186,12 @@ your project</a>.</p> following:</p> <ol> - <li><strong>Add your Android Market public key to the sample application code.</strong> + <li><strong>Add your Google Play public key to the sample application code.</strong> <p>This enables the application to verify the signature of the transaction information that is - returned from Android Market. To add your public key to the sample application code, do the + returned from Google Play. To add your public key to the sample application code, do the following:</p> <ol> - <li>Log in to your Android Market <a href="http://market.android.com/publish">publisher + <li>Log in to your Google Play <a href="http://play.google.com/apps/publish">publisher account</a>.</li> <li>On the upper left part of the page, under your name, click <strong>Edit Profile</strong>.</li> @@ -208,7 +208,7 @@ following:</p> </ol> </li> <li><strong>Change the package name of the sample application.</strong> - <p>The current package name is <code>com.example.dungeons</code>. Android Market does not let + <p>The current package name is <code>com.example.dungeons</code>. Google Play does not let you upload applications with package names that contain <code>com.example</code>, so you must change the package name to something else.</p> </li> @@ -221,14 +221,14 @@ following:</p> <h3>Uploading the sample application</h3> <p>After you build a release version of the sample application and sign it, you need to upload it as -a draft to the Android Market publisher site. You also need to create a product list for the in-app +a draft to the Google Play publisher site. You also need to create a product list for the in-app items that are available for purchase in the sample application. The following instructions show you how to do this.</p> <ol> - <li><strong>Upload the release version of the sample application to Android Market.</strong> + <li><strong>Upload the release version of the sample application to Google Play.</strong> <p>Do not publish the sample application; leave it as an unpublished draft application. The sample application is for demonstration purposes only and should not be made publicly available - on Android Market. To learn how to upload an application to Android Market, see <a + on Google Play. To learn how to upload an application to Google Play, see <a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading applications</a>.</p> </li> @@ -253,7 +253,7 @@ how to do this.</p> onto a device to run it. To run the sample application, do the following:</p> <ol> - <li><strong>Make sure you have at least one test account registered under your Android Market + <li><strong>Make sure you have at least one test account registered under your Google Play publisher account.</strong> <p>You cannot purchase items from yourself (Google Checkout prohibits this), so you need to create at least one test account that you can use to purchase items in the sample application. @@ -261,18 +261,18 @@ onto a device to run it. To run the sample application, do the following:</p> href="{@docRoot}guide/market/billing/billing_testing.html#billing-testing-setup">Setting up Test Accounts</a>.</p> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Install the application onto your device.</strong> - <p>Even though you uploaded the application to Android Market, the application is not published, - so you cannot download it from Android Market to a device. Instead, you must install the + <p>Even though you uploaded the application to Google Play, the application is not published, + so you cannot download it from Google Play to a device. Instead, you must install the application onto your device. To learn how to install an application onto a device, see <a href="{@docRoot}guide/developing/building/building-cmdline.html#RunningOnDevice">Running on a device</a>.</p> @@ -280,7 +280,7 @@ onto a device to run it. To run the sample application, do the following:</p> <li><strong>Make one of your test accounts the primary account on your device.</strong> <p>The primary account on your device must be one of the <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">test accounts</a> - that you registered on the Android Market site. If the primary account on your device is not a + that you registered on the Google Play publisher site. If the primary account on your device is not a test account, you must do a factory reset of the device and then sign in with one of your test accounts. To perform a factory reset, do the following:</p> <ol> @@ -306,7 +306,7 @@ to <code>true</code> in the <code>Consts.java</code> file.</p> <h2 id="billing-add-aidl">Adding the AIDL file to your project</h2> <p>The sample application contains an Android Interface Definition Language (AIDL) file, which -defines the interface to Android Market's in-app billing service +defines the interface to Google Play's in-app billing service (<code>MarketBillingService</code>). When you add this file to your project, the Android build environment creates an interface file (<code>IMarketBillingService.java</code>). You can then use this interface to make billing requests by invoking IPC method calls.</p> @@ -333,29 +333,29 @@ the <code>gen</code> folder of your project.</p> <h2 id="billing-permission">Updating Your Application's Manifest</h2> -<p>In-app billing relies on the Android Market application, which handles all communication between -your application and the Android Market server. To use the Android Market application, your +<p>In-app billing relies on the Google Play application, which handles all communication between +your application and the Google Play server. To use the Google Play application, your application must request the proper permission. You can do this by adding the <code>com.android.vending.BILLING</code> permission to your AndroidManifest.xml file. If your application does not declare the in-app billing permission, but attempts to send billing requests, -Android Market will refuse the requests and respond with a <code>RESULT_DEVELOPER_ERROR</code> +Google Play will refuse the requests and respond with a <code>RESULT_DEVELOPER_ERROR</code> response code.</p> <p>In addition to the billing permission, you need to declare the {@link android.content.BroadcastReceiver} that you will use to receive asynchronous response messages -(broadcast intents) from Android Market, and you need to declare the {@link android.app.Service} -that you will use to bind with the <code>IMarketBillingService</code> and send messages to Android -Market. You must also declare <a +(broadcast intents) from Google Play, and you need to declare the {@link android.app.Service} +that you will use to bind with the <code>IMarketBillingService</code> and send messages to Google +Play. You must also declare <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">intent filters</a> for the {@link android.content.BroadcastReceiver} so that the Android system knows how to handle the broadcast -intents that are sent from the Android Market application.</p> +intents that are sent from the Google Play application.</p> <p>For example, here is how the in-app billing sample application declares the billing permission, the {@link android.content.BroadcastReceiver}, the {@link android.app.Service}, and the intent filters. In the sample application, <code>BillingReceiver</code> is the {@link -android.content.BroadcastReceiver} that handles broadcast intents from the Android Market +android.content.BroadcastReceiver} that handles broadcast intents from the Google Play application and <code>BillingService</code> is the {@link android.app.Service} that sends requests -to the Android Market application.</p> +to the Google Play application.</p> <pre> <?xml version="1.0" encoding="utf-8"?> @@ -391,11 +391,11 @@ to the Android Market application.</p> <h2 id="billing-service">Creating a Local Service</h2> <p>Your application must have a local {@link android.app.Service} to facilitate messaging between -your application and Android Market. At a minimum, this service must do the following:</p> +your application and Google Play. At a minimum, this service must do the following:</p> <ul> <li>Bind to the <code>MarketBillingService</code>. - <li>Send billing requests (as IPC method calls) to the Android Market application. The five types + <li>Send billing requests (as IPC method calls) to the Google Play application. The five types of billing requests include: <ul> <li><code>CHECK_BILLING_SUPPORTED</code> requests</li> @@ -474,7 +474,7 @@ The five request types are specified using the <code>BILLING_REQUEST</code> Bund key can have the following five values:</p> <ul> - <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Android Market application + <li><code>CHECK_BILLING_SUPPORTED</code>—verifies that the Google Play application supports in-app billing.</li> <li><code>REQUEST_PURCHASE</code>—sends a purchase request for an in-app item.</li> <li><code>GET_PURCHASE_INFORMATION</code>—retrieves transaction information for a purchase @@ -510,7 +510,7 @@ application's main thread.</p> <h4>Verifying that in-app billing is supported (CHECK_BILLING_SUPPPORTED)</h4> -<p>The following code sample shows how to verify whether the Android Market application supports +<p>The following code sample shows how to verify whether the Google Play application supports in-app billing. In the sample, <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p> @@ -533,7 +533,7 @@ android.os.Bundle} response, which contains only a single key: <code>RESPONSE_CO <li><code>RESULT_BILLING_UNAVAILABLE</code>—in-app billing is not available because the API version you specified is not recognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that prohibits in-app purchases).</li> - <li><code>RESULT_ERROR</code>—there was an error connecting with the Android Market + <li><code>RESULT_ERROR</code>—there was an error connecting with the Google Play application.</li> <li><code>RESULT_DEVELOPER_ERROR</code>—the application is trying to make an in-app billing request but the application has not declared the <code>com.android.vending.BILLING</code> @@ -546,10 +546,10 @@ android.os.Bundle} response, which contains only a single key: <code>RESPONSE_CO <p>We recommend that you invoke the <code>CHECK_BILLING_SUPPORTED</code> request within a <code>RemoteException</code> block. When your code throws a <code>RemoteException</code> it -indicates that the remote method call failed, which means that the Android Market application is out +indicates that the remote method call failed, which means that the Google Play application is out of date and needs to be updated. In this case, you can provide users with an error message that contains a link to the <a -href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android Market</a> +href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google Play</a> Help topic.</p> <p>The sample application demonstrates how you can handle this error condition (see @@ -561,16 +561,16 @@ Help topic.</p> <ul> <li>Send the <code>REQUEST_PURCHASE</code> request.</li> - <li>Launch the {@link android.app.PendingIntent} that is returned from the Android Market + <li>Launch the {@link android.app.PendingIntent} that is returned from the Google Play application.</li> - <li>Handle the broadcast intents that are sent by the Android Market application.</li> + <li>Handle the broadcast intents that are sent by the Google Play application.</li> </ul> <h5>Making the request</h5> <p>You must specify four keys in the request {@link android.os.Bundle}. The following code sample shows how to set these keys and make a purchase request for a single in-app item. In the sample, -<code>mProductId</code> is the Android Market product ID of an in-app item (which is listed in the +<code>mProductId</code> is the Google Play product ID of an in-app item (which is listed in the application's <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-list-setup">product list</a>), and <code>mService</code> is an instance of the <code>MarketBillingService</code> interface.</p> @@ -644,25 +644,25 @@ void startBuyPageActivity(PendingIntent pendingIntent, Intent intent) { context and not an application context. Also, you cannot use the <code>singleTop</code> <a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launch mode</a> to launch the pending intent. If you do either of these, the Android system will not attach the pending intent to -your application process. Instead, it will bring Android Market to the foreground, disrupting your +your application process. Instead, it will bring Google Play to the foreground, disrupting your application.</p> <h5>Handling broadcast intents</h5> <p>A <code>REQUEST_PURCHASE</code> request also triggers two asynchronous responses (broadcast -intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> broadcast intent, +intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides error information about the request. If the request does not generate an error, the <code>RESPONSE_CODE</code> broadcast intent returns <code>RESULT_OK</code>, which indicates that the request was successfully sent. (To be clear, a <code>RESULT_OK</code> response does not indicate that the requested purchase was successful; it indicates that the request was sent -successfully to Android Market.)</p> +successfully to Google Play.)</p> <p>Next, when the requested transaction changes state (for example, the purchase is successfully -charged to a credit card or the user cancels the purchase), the Android Market application sends an +charged to a credit card or the user cancels the purchase), the Google Play application sends an <code>IN_APP_NOTIFY</code> broadcast intent. This message contains a notification ID, which you can use to retrieve the transaction details for the <code>REQUEST_PURCHASE</code> request.</p> -<p class="note"><strong>Note:</strong> The Android Market application also sends +<p class="note"><strong>Note:</strong> The Google Play application also sends an <code>IN_APP_NOTIFY</code> for refunds. For more information, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a>.</p> @@ -670,7 +670,7 @@ IN_APP_NOTIFY messages</a>.</p> <p>Because the purchase process is not instantaneous and can take several seconds (or more), you must assume that a purchase request is pending from the time you receive a <code>RESULT_OK</code> message until you receive an <code>IN_APP_NOTIFY</code> message for the transaction. While the -transaction is pending, the Android Market checkout UI displays an "Authorizing purchase..." +transaction is pending, the Google Play checkout UI displays an "Authorizing purchase..." notification; however, this notification is dismissed after 60 seconds and you should not rely on this notification as your primary means of conveying transaction status to users. Instead, we recommend that you do the following:</p> @@ -693,12 +693,12 @@ status of pending and completed in-app purchases.</p> be sure that your pending status UI does not block your application. For example, you should avoid using a hovering progress wheel to convey the status of a pending transaction because a pending transaction could last a long time, particularly if a device loses network connectivity and cannot -receive transaction updates from Android Market.</p> +receive transaction updates from Google Play.</p> <p class="caution"><strong>Important:</strong> If a user purchases a managed item, you must prevent the user from purchasing the item again while the original transaction is pending. If a user -attempts to purchase a managed item twice, and the first transaction is still pending, Android -Market will display an error to the user; however, Android Market will not send an error to your +attempts to purchase a managed item twice, and the first transaction is still pending, Google +Play will display an error to the user; however, Google Play will not send an error to your application notifying you that the second purchase request was canceled. This might cause your application to get stuck in a pending state while it waits for an <code>IN_APP_NOTIFY</code> message for the second purchase request.</p> @@ -730,7 +730,7 @@ three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional keys are then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you -must generate. The Android Market application returns this nonce with the +must generate. The Google Play application returns this nonce with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information. The <code>NOTIFY_IDS</code> key contains an array of notification IDs, which you received in the <code>IN_APP_NOTIFY</code> broadcast intent.</p> @@ -741,9 +741,9 @@ you with the status of the request and the <code>REQUEST_ID</code> key provides request identifier for the request.</p> <p>A <code>GET_PURCHASE_INFORMATION</code> request also triggers two asynchronous responses -(broadcast intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> +(broadcast intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the -request was successful, the Android Market application sends a <code>PURCHASE_STATE_CHANGED</code> +request was successful, the Google Play application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p> @@ -783,8 +783,8 @@ request identifier for the request.</p> <code>RESPONSE_CODE</code> broadcast intent. This broadcast intent provides status and error information about the request.</p> -<p>You must send a confirmation when you receive transaction information from Android Market. If you -don't send a confirmation message, Android Market will continue sending +<p>You must send a confirmation when you receive transaction information from Google Play. If you +don't send a confirmation message, Google Play will continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not confirmed. Also, your application must be able to handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p> @@ -792,7 +792,7 @@ orders.</p> <p>In addition, as a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for a purchased item until you have delivered the item to the user. This way, if your application crashes or something else prevents your application from delivering the product, your application -will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating +will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating that you need to deliver the product.</p> <h4>Restoring transaction information (RESTORE_TRANSACTIONS)</h4> @@ -817,7 +817,7 @@ three keys that are required for all requests: <code>BILLING_REQUEST</code>, <code>API_VERSION</code>, and <code>PACKAGE_NAME</code>. The additional <code>REQUEST_NONCE</code> key is then added to the bundle prior to invoking the <code>sendBillingRequest()</code> method. The <code>REQUEST_NONCE</code> key contains a cryptographically secure nonce (number used once) that you -must generate. The Android Market application returns this nonce with the transactions information +must generate. The Google Play application returns this nonce with the transactions information contained in the <code>PURCHASE_STATE_CHANGED</code> broadcast intent so you can verify the integrity of the transaction information.</p> @@ -827,9 +827,9 @@ you with the status of the request and the <code>REQUEST_ID</code> key provides request identifier for the request.</p> <p>A <code>RESTORE_TRANSACTIONS</code> request also triggers two asynchronous responses (broadcast -intents). First, the Android Market application sends a <code>RESPONSE_CODE</code> broadcast intent, +intents). First, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status and error information about the request. Next, if the request was successful, -the Android Market application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This +the Google Play application sends a <code>PURCHASE_STATE_CHANGED</code> broadcast intent. This message contains the detailed transaction information. The transaction information is contained in a signed JSON string (unencrypted). The message includes the signature so you can verify the integrity of the signed string.</p> @@ -842,7 +842,7 @@ application has been removed from a device and reinstalled.</p> <p>You may also want your {@link android.app.Service} to receive intent messages from your {@link android.content.BroadcastReceiver}. You can use these intent messages to convey the information that -was sent asynchronously from the Android Market application to your {@link +was sent asynchronously from the Google Play application to your {@link android.content.BroadcastReceiver}. To see an example of how you can send and receive these intent messages, see the <code>BillingReceiver.java</code> and <code>BillingService.java</code> files in the sample application. You can use these samples as a basis for your own implementation. However, @@ -851,16 +851,16 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D <h2 id="billing-broadcast-receiver">Creating a BroadcastReceiver</h2> -<p>The Android Market application uses broadcast intents to send asynchronous billing responses to +<p>The Google Play application uses broadcast intents to send asynchronous billing responses to your application. To receive these intent messages, you need to create a {@link android.content.BroadcastReceiver} that can handle the following intents:</p> <ul> <li>com.android.vending.billing.RESPONSE_CODE - <p>This broadcast intent contains an Android Market response code, and is sent after you make an + <p>This broadcast intent contains a Google Play response code, and is sent after you make an in-app billing request. For more information about the response codes that are sent with this response, see <a - href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Android Market Response + href="{@docRoot}guide/market/billing/billing_reference.html#billing-codes">Google Play Response Codes for In-app Billing</a>.</p> </li> <li>com.android.vending.billing.IN_APP_NOTIFY @@ -895,18 +895,18 @@ sent in response to billing requests.</p> <td><code>com.android.vending.billing.RESPONSE_CODE</code></td> <td><code>request_id</code></td> <td>A <code>long</code> representing a request ID. A request ID identifies a specific billing - request and is returned by Android Market at the time a request is made.</td> + request and is returned by Google Play at the time a request is made.</td> </tr> <tr> <td><code>com.android.vending.billing.RESPONSE_CODE</code></td> <td><code>response_code</code></td> - <td>An <code>int</code> representing the actual Android Market server response code.</td> + <td>An <code>int</code> representing the actual Google Play server response code.</td> </tr> <tr> <td><code>com.android.vending.billing.IN_APP_NOTIFY</code></td> <td><code>notification_id</code></td> <td>A <code>String</code> representing the notification ID for a given purchase state change. - Android Market notifies you when there is a purchase state change and the notification includes a + Google Play notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</td> </tr> @@ -933,16 +933,16 @@ public class BillingReceiver extends BroadcastReceiver { private static final String TAG = "BillingReceiver"; - // Intent actions that we receive in the BillingReceiver from Android Market. - // These are defined by Android Market and cannot be changed. + // Intent actions that we receive in the BillingReceiver from Google Play. + // These are defined by Google Play and cannot be changed. // The sample application defines these in the Consts.java file. public static final String ACTION_NOTIFY = "com.android.vending.billing.IN_APP_NOTIFY"; public static final String ACTION_RESPONSE_CODE = "com.android.vending.billing.RESPONSE_CODE"; public static final String ACTION_PURCHASE_STATE_CHANGED = "com.android.vending.billing.PURCHASE_STATE_CHANGED"; - // The intent extras that are passed in an intent from Android Market. - // These are defined by Android Market and cannot be changed. + // The intent extras that are passed in an intent from Google Play. + // These are defined by Google Play and cannot be changed. // The sample application defines these in the Consts.java file. public static final String NOTIFICATION_ID = "notification_id"; public static final String INAPP_SIGNED_DATA = "inapp_signed_data"; @@ -974,7 +974,7 @@ public class BillingReceiver extends BroadcastReceiver { } </pre> -<p>In addition to receiving broadcast intents from the Android Market application, your {@link +<p>In addition to receiving broadcast intents from the Google Play application, your {@link android.content.BroadcastReceiver} must handle the information it received in the broadcast intents. Usually, your {@link android.content.BroadcastReceiver} does this by sending the information to a local service (discussed in the next section). The <code>BillingReceiver.java</code> file in the @@ -985,8 +985,8 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D <h2 id="billing-signatures">Verifying Signatures and Nonces</h2> -<p>Android Market's in-app billing service uses two mechanisms to help verify the integrity of the -transaction information you receive from Android Market: nonces and signatures. A nonce (number used +<p>Google Play's in-app billing service uses two mechanisms to help verify the integrity of the +transaction information you receive from Google Play: nonces and signatures. A nonce (number used once) is a cryptographically secure number that your application generates and sends with every <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, enabling you to verify that @@ -1023,12 +1023,12 @@ implementation, be sure to follow the guidelines in <a href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and Design</a> and obfuscate your code.</p> -<p>You will need to use your Android Market public key to perform the signature verification. The -following procedure shows you how to retrieve Base64-encoded public key from the Android Market +<p>You will need to use your Google Play public key to perform the signature verification. The +following procedure shows you how to retrieve Base64-encoded public key from the Google Play publisher site.</p> <ol> - <li>Log in to your <a href="http://market.android.com/publish">publisher account</a>.</li> + <li>Log in to your <a href="http://play.google.com/apps/publish">publisher account</a>.</li> <li>On the upper left part of the page, under your name, click <strong>Edit profile</strong>.</li> <li>On the Edit Profile page, scroll down to the Licensing & In-app Billing panel (see figure 2).</li> @@ -1080,8 +1080,8 @@ unmanaged items is important because unmanaged items cannot be restored by using <h3>Creating a user interface for selecting items</h3> -<p>You must provide users with a means for selecting items that they want to purchase. Android -Market provides the checkout user interface (which is where the user provides a form of payment and +<p>You must provide users with a means for selecting items that they want to purchase. Google +Play provides the checkout user interface (which is where the user provides a form of payment and approves the purchase), but your application must provide a control (widget) that invokes the <code>sendBillingRequest()</code> method when a user selects an item for purchase.</p> diff --git a/docs/html/guide/market/billing/billing_overview.jd b/docs/html/guide/market/billing/billing_overview.jd index 8f9fd4c..b593811 100755 --- a/docs/html/guide/market/billing/billing_overview.jd +++ b/docs/html/guide/market/billing/billing_overview.jd @@ -38,24 +38,24 @@ parent.link=index.html </div> </div> -<p>Android Market In-app Billing is an Android Market service that provides checkout processing for +<p>In-app Billing is a Google Play service that provides checkout processing for in-app purchases. To use the service, your application sends a billing request for a specific in-app product. The service then handles all of the checkout details for the transaction, including requesting and validating the form of payment and processing the financial transaction. When the checkout process is complete, the service sends your application the purchase details, such as the order number, the order date and time, and the price paid. At no point does your application have to -handle any financial transactions; that role is provided by Android Market's in-app billing +handle any financial transactions; that role is provided by Google Play's in-app billing service.</p> <h2 id="billing-arch">In-app Billing Architecture</h2> <p>In-app billing uses an asynchronous message loop to convey billing requests and billing responses -between your application and the Android Market server. In practice, your application never directly -communicates with the Android Market server (see figure 1). Instead, your application sends billing -requests to the Android Market application over interprocess communication (IPC) and receives -purchase responses from the Android Market application in the form of asynchronous broadcast -intents. Your application does not manage any network connections between itself and the Android -Market server or use any special APIs from the Android platform.</p> +between your application and the Google Play server. In practice, your application never directly +communicates with the Google Play server (see figure 1). Instead, your application sends billing +requests to the Google Play application over interprocess communication (IPC) and receives +purchase responses from the Google Play application in the form of asynchronous broadcast +intents. Your application does not manage any network connections between itself and the Google +Play server or use any special APIs from the Android platform.</p> <p>Some in-app billing implementations may also use a private remote server to deliver content or validate transactions, but a remote server is not required to implement in-app billing. A remote @@ -70,16 +70,16 @@ to security attacks.</p> <img src="{@docRoot}images/billing_arch.png" alt="" height="582" /> <p class="img-caption"> <strong>Figure 1.</strong> Your application sends and receives billing messages through the - Android Market application, which handles all communication with the Android Market server.</p> + Google Play application, which handles all communication with the Google Play server.</p> </div> <p>A typical in-app billing implementation relies on three components:</p> <ul> <li>A {@link android.app.Service} (named <code>BillingService</code> in the sample application), - which processes purchase messages from the application and sends billing requests to Android - Market's in-app billing service.</li> + which processes purchase messages from the application and sends billing requests to the Google + Play in-app billing service.</li> <li>A {@link android.content.BroadcastReceiver} (named <code>BillingReceiver</code> in the sample - application), which receives all asynchronous billing responses from the Android Market + application), which receives all asynchronous billing responses from the Google Play application.</li> <li>A security component (named <code>Security</code> in the sample application), which performs security-related tasks, such as signature verification and nonce generation. For more information @@ -99,19 +99,19 @@ to security attacks.</p> <p>In addition to these components, your application must provide a way to store information about users' purchases and some sort of user interface that lets users select items to purchase. You do -not need to provide a checkout user interface. When a user initiates an in-app purchase, the Android -Market application presents the checkout user interface to your user. When the user completes the +not need to provide a checkout user interface. When a user initiates an in-app purchase, the Google +Play application presents the checkout user interface to your user. When the user completes the checkout process, your application resumes.</p> <h2 id="billing-msgs">In-app Billing Messages</h2> -<p>When the user initiates a purchase, your application sends billing messages to Android Market's +<p>When the user initiates a purchase, your application sends billing messages to Google Play's in-app billing service (named <code>MarketBillingService</code>) using simple IPC method calls. The -Android Market application responds to all billing requests synchronously, providing your -application with status notifications and other information. The Android Market application also +Google Play application responds to all billing requests synchronously, providing your +application with status notifications and other information. The Google Play application also responds to some billing requests asynchronously, providing your application with error messages and detailed transaction information. The following section describes the basic request-response -messaging that takes place between your application and the Android Market application.</p> +messaging that takes place between your application and the Google Play application.</p> <h3 id="billing-request">In-app billing requests</h3> @@ -133,31 +133,31 @@ Service Interface</a>. <p>One of the most important keys that every request Bundle must have is the <code>BILLING_REQUEST</code> key. This key lets you specify the type of billing request you are -making. Android Market's in-app billing service supports the following five types of billing +making. Google Play's in-app billing service supports the following five types of billing requests:</p> <ul> <li><code>CHECK_BILLING_SUPPORTED</code> - <p>This request verifies that the Android Market application supports in-app billing. You + <p>This request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p> </li> <li><code>REQUEST_PURCHASE</code> - <p>This request sends a purchase message to the Android Market application and is the foundation + <p>This request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase - an item in your application. Android Market then handles the financial transaction by displaying + an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.</p> </li> <li><code>GET_PURCHASE_INFORMATION</code> <p>This request retrieves the details of a purchase state change. A purchase changes state when a requested purchase is billed successfully or when a user cancels a transaction during - checkout. It can also occur when a previous purchase is refunded. Android Market notifies your + checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p> </li> <li><code>CONFIRM_NOTIFICATIONS</code> <p>This request acknowledges that your application received the details of a purchase state - change. Android Market sends purchase state change notifications to your application until you + change. Google Play sends purchase state change notifications to your application until you confirm that you received them.</p> </li> <li><code>RESTORE_TRANSACTIONS</code> @@ -171,7 +171,7 @@ requests:</p> <h3 id="billing-response">In-app Billing Responses</h3> -<p>The Android Market application responds to in-app billing requests with both synchronous and +<p>The Google Play application responds to in-app billing requests with both synchronous and asynchronous responses. The synchronous response is a {@link android.os.Bundle} with the following three keys:</p> @@ -196,9 +196,9 @@ include the following:</p> <ul> <li><code>com.android.vending.billing.RESPONSE_CODE</code> - <p>This response contains an Android Market server response code, and is sent after you make an + <p>This response contains a Google Play server response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was - successfully sent to Android Market or it can indicate that some error occurred during a billing + successfully sent to Google Play or it can indicate that some error occurred during a billing request. This response is <em>not</em> used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a @@ -253,7 +253,7 @@ broadcast intents that are sent for every request.</p> <ol> <li>Your application sends a purchase request (<code>REQUEST_PURCHASE</code> type), specifying a product ID and other parameters.</li> - <li>The Android Market application sends your application a Bundle with the following keys: + <li>The Google Play application sends your application a Bundle with the following keys: <code>RESPONSE_CODE</code>, <code>PURCHASE_INTENT</code>, and <code>REQUEST_ID</code>. The <code>PURCHASE_INTENT</code> key provides a {@link android.app.PendingIntent}, which your application uses to start the checkout UI for the given product ID.</li> @@ -262,20 +262,20 @@ broadcast intents that are sent for every request.</p> context and not an application context.</p> </li> <li>When the checkout flow finishes (that is, the user successfully purchases the item or cancels - the purchase), Android Market sends your application a notification message (an + the purchase), Google Play sends your application a notification message (an <code>IN_APP_NOTIFY</code> broadcast intent). The notification message includes a notification ID, which references the transaction.</li> <li>Your application requests the transaction information by sending a <code>GET_PURCHASE_STATE_CHANGED</code> request, specifying the notification ID for the transaction.</li> - <li>The Android Market application sends a Bundle with a <code>RESPONSE_CODE</code> key and a + <li>The Google Play application sends a Bundle with a <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. - <li>Android Market sends the transaction information to your application in a + <li>Google Play sends the transaction information to your application in a <code>PURCHASE_STATE_CHANGED</code> broadcast intent.</li> <li>Your application confirms that you received the transaction information for the given notification ID by sending a confirmation message (<code>CONFIRM_NOTIFICATIONS</code> type), specifying the notification ID for which you received transaction information.</li> - <li>The Android Market application sends your application a Bundle with a + <li>The Google Play application sends your application a Bundle with a <code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key.</li> </ol> @@ -284,13 +284,13 @@ broadcast intents that are sent for every request.</p> <strong>Figure 2.</strong> Message sequence for a purchase request. </p> -<p>Keep in mind, you must send a confirmation when you receive transaction information from Android -Market (step 8 in figure 2). If you don't send a confirmation message, Android Market will +<p>Keep in mind, you must send a confirmation when you receive transaction information from Google +Play (step 8 in figure 2). If you don't send a confirmation message, Google Play will continue sending <code>IN_APP_NOTIFY</code> messages for the transactions you have not confirmed. As a best practice, you should not send a <code>CONFIRM_NOTIFICATIONS</code> request for a purchased item until you have delivered the item to the user. This way, if your application crashes or something else prevents your application from delivering the product, your application -will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Android Market indicating +will still receive an <code>IN_APP_NOTIFY</code> broadcast intent from Google Play indicating that you need to deliver the product. Also, as a best practice, your application must be able to handle <code>IN_APP_NOTIFY</code> messages that contain multiple orders.</p> @@ -307,7 +307,7 @@ broadcast intents that are sent for every request.</p> </div> <p>The request triggers three responses. The first is a {@link android.os.Bundle} with a -<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Android Market +<code>RESPONSE_CODE</code> key and a <code>REQUEST_ID</code> key. Next, the Google Play application sends a <code>RESPONSE_CODE</code> broadcast intent, which provides status information or error information about the request. As always, the <code>RESPONSE_CODE</code> message references a specific request ID, so you can determine which request a <code>RESPONSE_CODE</code> message @@ -338,18 +338,18 @@ is supported; a <code>RESULT_BILLING_UNAVAILABLE</code> response code indicates is unavailable because the API version you specified is unrecognized or the user is not eligible to make in-app purchases (for example, the user resides in a country that does not allow in-app billing). A <code>SERVER_ERROR</code> can also be returned, indicating that there was a problem with -the Android Market server.</p> +the Google Play server.</p> <h3 id="billing-action-notify">Handling IN_APP_NOTIFY messages</h3> -<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Android -Market in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The +<p>Usually, your application receives an <code>IN_APP_NOTIFY</code> broadcast intent from Google +Play in response to a <code>REQUEST_PURCHASE</code> message (see figure 2). The <code>IN_APP_NOTIFY</code> broadcast intent informs your application that the state of a requested purchase has changed. To retrieve the details of that purchase, your application sends a -<code>GET_PURCHASE_INFORMATION</code> request. Android Market responds with a +<code>GET_PURCHASE_INFORMATION</code> request. Google Play responds with a <code>PURCHASE_STATE_CHANGED</code> broadcast intent, which contains the details of the purchase state change. Your application then sends a <code>CONFIRM_NOTIFICATIONS</code> message, informing -Android Market that you have received the purchase state change information.</p> +Google Play that you have received the purchase state change information.</p> <p>In some special cases, you may receive multiple <code>IN_APP_NOTIFY</code> messages even though you have confirmed receipt of the purchase information, or you may receive @@ -358,13 +358,13 @@ purchase. Your application must handle both of these special cases.</p> <h4>Handling multiple IN_APP_NOTIFY messages</h4> -<p>When Android Market receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given +<p>When Google Play receives a <code>CONFIRM_NOTIFICATIONS</code> message for a given <code>PURCHASE_STATE_CHANGED</code> message, it usually stops sending <code>IN_APP_NOTIFY</code> -intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Android -Market may send repeated <code>IN_APP_NOTIFY</code> intents for a +intents for that <code>PURCHASE_STATE_CHANGED</code> message. Sometimes, however, Google +Play may send repeated <code>IN_APP_NOTIFY</code> intents for a <code>PURCHASE_STATE_CHANGED</code> message even though your application has sent a <code>CONFIRM_NOTIFICATIONS</code> message. This can occur if a device loses network connectivity -while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Android Market +while you are sending the <code>CONFIRM_NOTIFICATIONS</code> message. In this case, Google Play might not receive your <code>CONFIRM_NOTIFICATIONS</code> message and it could send multiple <code>IN_APP_NOTIFY</code> messages until it receives acknowledgement that you received the transaction message. Therefore, your application must be able to recognize that the subsequent @@ -390,7 +390,7 @@ IN_APP_NOTIFY messages.</p> <p>In the first case, your application may receive an <code>IN_APP_NOTIFY</code> broadcast intent when a user has your application installed on two (or more) devices and the user makes an in-app -purchase from one of the devices. In this case, Android Market sends an <code>IN_APP_NOTIFY</code> +purchase from one of the devices. In this case, Google Play sends an <code>IN_APP_NOTIFY</code> message to the second device, informing the application that there is a purchase state change. Your application can handle this message the same way it handles the response from an application-initiated <code>REQUEST_PURCHASE</code> message, so that ultimately your application @@ -400,8 +400,8 @@ href="{@docRoot}guide/market/billing/billing_admin.html#billing-purchase-type">p to "managed per user account."</p> <p>In the second case, your application can receive an <code>IN_APP_NOTIFY</code> broadcast intent -when Android Market receives a refund notification from Google Checkout. In this case, Android -Market sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle +when Google Play receives a refund notification from Google Checkout. In this case, Google +Play sends an <code>IN_APP_NOTIFY</code> message to your application. Your application can handle this message the same way it handles responses from an application-initiated <code>REQUEST_PURCHASE</code> message so that ultimately your application receives a <code>PURCHASE_STATE_CHANGED</code> message that includes information about the item that has been @@ -417,13 +417,13 @@ information.</p> <h2 id="billing-security">Security Controls</h2> <p>To help ensure the integrity of the transaction information that is sent to your application, -Android Market signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code> -broadcast intent. Android Market uses the private key that is associated with your publisher account +Google Play signs the JSON string that is contained in the <code>PURCHASE_STATE_CHANGED</code> +broadcast intent. Google Play uses the private key that is associated with your publisher account to create this signature. The publisher site generates an RSA key pair for each publisher account. You can find the public key portion of this key pair on your account's profile page. It is the same -public key that is used with Android Market licensing.</p> +public key that is used with Google Play licensing.</p> -<p>When Android Market signs a billing response, it includes the signed JSON string (unencrypted) +<p>When Google Play signs a billing response, it includes the signed JSON string (unencrypted) and the signature. When your application receives this signed response you can use the public key portion of your RSA key pair to verify the signature. By performing signature verification you can help detect responses that have been tampered with or that have been spoofed. You can perform this @@ -431,9 +431,9 @@ signature verification step in your application; however, if your application co remote server then we recommend that you perform the signature verification on that server.</p> <p>In-app billing also uses nonces (a random number used once) to help verify the integrity of the -purchase information that's returned from Android Market. Your application must generate a nonce and +purchase information that's returned from Google Play. Your application must generate a nonce and send it with a <code>GET_PURCHASE_INFORMATION</code> request and a <code>RESTORE_TRANSACTIONS</code> -request. When Android Market receives the request, it adds the nonce to the JSON string that +request. When Google Play receives the request, it adds the nonce to the JSON string that contains the transaction information. The JSON string is then signed and returned to your application. When your application receives the JSON string, you need to verify the nonce as well as the signature of the JSON string.</p> @@ -447,20 +447,20 @@ href="{@docRoot}guide/market/billing/billing_best_practices.html">Security and D limitations.</p> <ul> - <li>In-app billing can be implemented only in applications that you publish through Android - Market.</li> - <li>You must have a Google Checkout Merchant account to use Android Market In-app Billing.</li> + <li>In-app billing can be implemented only in applications that you publish through Google + Play.</li> + <li>You must have a Google Checkout Merchant account to use Google Play In-app Billing.</li> <li>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application.</li> + requires version 2.3.4 (or higher) of the Google Play application.</li> <li>An application can use in-app billing only if the device is running Android 1.6 (API level 4) or higher.</li> <li>You can use in-app billing to sell only digital content. You cannot use in-app billing to sell physical goods, personal services, or anything that requires physical delivery.</li> - <li>Android Market does not provide any form of content delivery. You are responsible for + <li>Google Play does not provide any form of content delivery. You are responsible for delivering the digital content that you sell in your applications.</li> <li>You cannot implement in-app billing on a device that never connects to the network. To - complete in-app purchase requests, a device must be able to access the Android Market server over + complete in-app purchase requests, a device must be able to access the Google Play server over the network. </li> </ul> diff --git a/docs/html/guide/market/billing/billing_reference.jd b/docs/html/guide/market/billing/billing_reference.jd index 5a7ba56..e8cf2ee 100755 --- a/docs/html/guide/market/billing/billing_reference.jd +++ b/docs/html/guide/market/billing/billing_reference.jd @@ -36,20 +36,20 @@ parent.link=index.html <p>The following document provides technical reference information for the following:</p> <ul> - <li><a href="#billing-codes">Android Market Server Response Codes for In-app Billing</a></li> + <li><a href="#billing-codes">Google Play Server Response Codes for In-app Billing</a></li> <li><a href="#billing-interface">In-app Billing Interface Parameters</a></li> <li><a href="#billing-intents">In-app Billing Broadcast Intents</a></li> </ul> -<h2 id="billing-codes">Android Market Server Response Codes for In-app Billing</h2> +<h2 id="billing-codes">Google Play Server Response Codes for In-app Billing</h2> -<p>The following table lists all of the server response codes that are sent from Android Market to -your application. Android Market sends these response codes asynchronously as +<p>The following table lists all of the server response codes that are sent from Google Play to +your application. Google Play sends these response codes asynchronously as <code>response_code</code> extras in the <code>com.android.vending.billing.RESPONSE_CODE</code> broadcast intent. Your application must handle all of these response codes.</p> <p class="table-caption" id="response-codes-table"><strong>Table 1.</strong> Summary of response -codes returned by Android Market.</p> +codes returned by Google Play.</p> <table> @@ -80,13 +80,13 @@ codes returned by Android Market.</p> <td><code>RESULT_BILLING_UNAVAILABLE</code></td> <td>3</td> <td>Indicates that in-app billing is not available because the <code>API_VERSION</code> that you - specified is not recognized by the Android Market application or the user is ineligible for in-app + specified is not recognized by the Google Play application or the user is ineligible for in-app billing (for example, the user resides in a country that prohibits in-app purchases).</td> </tr> <tr> <td><code>RESULT_ITEM_UNAVAILABLE</code></td> <td>4</td> - <td>Indicates that Android Market cannot find the requested item in the application's product + <td>Indicates that Google Play cannot find the requested item in the application's product list. This can happen if the product ID is misspelled in your <code>REQUEST_PURCHASE</code> request or if an item is unpublished in the application's product list.</td> </tr> @@ -108,7 +108,7 @@ purchase an item from yourself, which is not allowed by Google Checkout.</td> <h2 id="billing-interface">In-app Billing Service Interface</h2> -<p>The following section describes the interface for Android Market's in-app billing service. The +<p>The following section describes the interface for Google Play's in-app billing service. The interface is defined in the <code>IMarketBillingService.aidl</code> file, which is included with the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample @@ -144,7 +144,7 @@ pairs, which are summarized in table 2.</p> <td><code>int</code></td> <td>1</td> <td>Yes</td> - <td>The version of Android Market's in-app billing service you are using. The current version is + <td>The version of Google Play's in-app billing service you are using. The current version is 1.</td> </tr> <tr> @@ -160,8 +160,8 @@ pairs, which are summarized in table 2.</p> <td>Any valid product identifier.</td> <td>Required for <code>REQUEST_PURCHASE</code> requests.</td> <td>The product ID of the item you are making a billing request for. Every in-app item that you - sell using Android Market's in-app billing service must have a unique product ID, which you - specify on the Android Market publisher site.</td> + sell using Google Play's in-app billing service must have a unique product ID, which you + specify on the Google Play publisher site.</td> </tr> <tr> <td><code>NONCE</code></td> @@ -172,7 +172,7 @@ pairs, which are summarized in table 2.</p> <td>A number used once. Your application must generate and send a nonce with each <code>GET_PURCHASE_INFORMATION</code> and <code>RESTORE_TRANSACTIONS</code> request. The nonce is returned with the <code>PURCHASE_STATE_CHANGED</code> broadcast intent, so you can use this value - to verify the integrity of transaction responses form Android Market.</td> + to verify the integrity of transaction responses form Google Play.</td> </tr> <tr> <td><code>NOTIFY_IDS</code></td> @@ -202,20 +202,20 @@ pairs, which are summarized in table 2.</p> <ul> <li><code>CHECK_BILLING_SUPPORTED</code> - <p>This request verifies that the Android Market application supports in-app billing. You + <p>This request verifies that the Google Play application supports in-app billing. You usually send this request when your application first starts up. This request is useful if you want to enable or disable certain UI features that are relevant only to in-app billing.</p> </li> <li><code>REQUEST_PURCHASE</code> - <p>This request sends a purchase message to the Android Market application and is the foundation + <p>This request sends a purchase message to the Google Play application and is the foundation of in-app billing. You send this request when a user indicates that he or she wants to purchase - an item in your application. Android Market then handles the financial transaction by displaying + an item in your application. Google Play then handles the financial transaction by displaying the checkout user interface.</p> </li> <li><code>GET_PURCHASE_INFORMATION</code> <p>This request retrieves the details of a purchase state change. A purchase state change can occur when a purchase request is billed successfully or when a user cancels a transaction during - checkout. It can also occur when a previous purchase is refunded. Android Market notifies your + checkout. It can also occur when a previous purchase is refunded. Google Play notifies your application when a purchase changes state, so you only need to send this request when there is transaction information to retrieve.</p> </li> @@ -294,8 +294,8 @@ each in-app billing request type.</p> <h2 id="billing-intents">In-app Billing Broadcast Intents</h2> -<p>The following section describes the in-app billing broadcast intents that are sent by the Android -Market application. These broadcast intents inform your application about in-app billing actions +<p>The following section describes the in-app billing broadcast intents that are sent by the Google +Play application. These broadcast intents inform your application about in-app billing actions that have occurred. Your application must implement a {@link android.content.BroadcastReceiver} to receive these broadcast intents, such as the <code>BillingReceiver</code> that's shown in the in-app billing <a href="{@docRoot}guide/market/billing/billing_integrate.html#billing-download">sample @@ -303,21 +303,21 @@ application</a>.</p> <h4>com.android.vending.billing.RESPONSE_CODE</h4> -<p>This broadcast intent contains an Android Market response code, and is sent after you make an +<p>This broadcast intent contains a Google Play response code, and is sent after you make an in-app billing request. A server response code can indicate that a billing request was successfully -sent to Android Market or it can indicate that some error occurred during a billing request. This +sent to Google Play or it can indicate that some error occurred during a billing request. This intent is not used to report any purchase state changes (such as refund or purchase information). For more information about the response codes that are sent with this response, see <a -href="#billing-codes">Android Market Response Codes for In-app Billing</a>. The sample application +href="#billing-codes">Google Play Response Codes for In-app Billing</a>. The sample application assigns this broadcast intent to a constant named <code>ACTION_RESPONSE_CODE</code>.</p> <h5>Extras</h5> <ul type="none"> <li><code>request_id</code>—a <code>long</code> representing a request ID. A request ID - identifies a specific billing request and is returned by Android Market at the time a request is + identifies a specific billing request and is returned by Google Play at the time a request is made.</li> - <li><code>response_code</code>—an <code>int</code> representing the Android Market server + <li><code>response_code</code>—an <code>int</code> representing the Google Play server response code.</li> </ul> @@ -335,7 +335,7 @@ message details. The sample application assigns this broadcast intent to a const <ul type="none"> <li><code>notification_id</code>—a <code>String</code> representing the notification ID for - a given purchase state change. Android Market notifies you when there is a purchase state change + a given purchase state change. Google Play notifies you when there is a purchase state change and the notification includes a unique notification ID. To get the details of the purchase state change, you send the notification ID with the <code>GET_PURCHASE_INFORMATION</code> request.</li> </ul> @@ -375,15 +375,15 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p> <tr> <td>nonce</td> <td>A number used once. Your application generates the nonce and sends it with the - <code>GET_PURCHASE_INFORMATION</code> request. Android Market sends the nonce back as part of the + <code>GET_PURCHASE_INFORMATION</code> request. Google Play sends the nonce back as part of the JSON string so you can verify the integrity of the message.</td> </tr> <tr> <td>notificationId</td> <td>A unique identifier that is sent with an <code>IN_APP_NOTIFY</code> broadcast intent. Each <code>notificationId</code> corresponds to a specify message that is waiting to be retrieved on - the Android Market server. Your application sends back the <code>notificationId</code> with the - <code>GET_PURCHASE_INFORMATION</code> message so Android Market can determine which messages you + the Google Play server. Your application sends back the <code>notificationId</code> with the + <code>GET_PURCHASE_INFORMATION</code> message so Google Play can determine which messages you are retrieving.</td> </tr> <tr> @@ -398,7 +398,7 @@ a <code>PURCHASE_STATE_CHANGED</code> intent.</p> <tr> <td>productId</td> <td>The item's product identifier. Every item has a product ID, which you must specify in the - application's product list on the Android Market publisher site.</td> + application's product list on the Google Play publisher site.</td> </tr> <tr> <td>purchaseTime</td> diff --git a/docs/html/guide/market/billing/billing_testing.jd b/docs/html/guide/market/billing/billing_testing.jd index 5453047..77aa3ed 100755 --- a/docs/html/guide/market/billing/billing_testing.jd +++ b/docs/html/guide/market/billing/billing_testing.jd @@ -32,16 +32,16 @@ parent.link=index.html </div> </div> -<p>The Android Market publisher site provides several tools that help you test your in-app billing +<p>The Google Play publisher site provides several tools that help you test your in-app billing implementation before it is published. You can use these tools to create test accounts and purchase special reserved items that send static billing responses to your application.</p> <p>To test in-app billing in an application you must install the application on an Android-powered device. You cannot use the Android emulator to test in-app billing. The device you use for testing must run a standard version of the Android 1.6 or later platform (API level 4 or higher), and have -the most current version of the Android Market application installed. If a device is not running the -most current Android Market application, your application won't be able to send in-app billing -requests to Android Market. For general information about how to set up a device for use in +the most current version of the Google Play application installed. If a device is not running the +most current Google Play application, your application won't be able to send in-app billing +requests to Google Play. For general information about how to set up a device for use in developing Android applications, see <a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p> @@ -50,12 +50,12 @@ Devices</a>.</p> <h2 id="billing-testing-static">Testing in-app purchases with static responses</h2> <p>We recommend that you first test your in-app billing implementation using static responses from -Android Market. This enables you to verify that your application is handling the primary Android -Market responses correctly and that your application is able to verify signatures correctly.</p> +Google Play. This enables you to verify that your application is handling the primary Google +Play responses correctly and that your application is able to verify signatures correctly.</p> <p>To test your implementation with static responses, you make an in-app billing request using a special item that has a reserved product ID. Each reserved product ID returns a specific static -response from Android Market. No money is transferred when you make in-app billing requests with the +response from Google Play. No money is transferred when you make in-app billing requests with the reserved product IDs. Also, you cannot specify the form of payment when you make a billing request with a reserved product ID. Figure 1 shows the checkout flow for the reserved item that has the product ID android.test.purchased.</p> @@ -65,7 +65,7 @@ product ID android.test.purchased.</p> <strong>Figure 1.</strong> Checkout flow for the special reserved item android.test.purchased. </p> -<p>You do not need to list the reserved products in your application's product list. Android Market +<p>You do not need to list the reserved products in your application's product list. Google Play already knows about the reserved product IDs. Also, you do not need to upload your application to the publisher site to perform static response tests with the reserved product IDs. You can simply install your application on a device, log into the device, and make billing requests using the @@ -75,24 +75,24 @@ reserved product IDs.</p> <ul> <li><strong>android.test.purchased</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as + <p>When you make an in-app billing request with this product ID, Google Play responds as though you successfully purchased an item. The response includes a JSON string, which contains fake purchase information (for example, a fake order ID). In some cases, the JSON string is signed and the response includes the signature so you can test your signature verification implementation using these responses.</p> </li> <li><strong>android.test.canceled</strong> - <p>When you make an in-app billing request with this product ID Android Market responds as + <p>When you make an in-app billing request with this product ID Google Play responds as though the purchase was canceled. This can occur when an error is encountered in the order process, such as an invalid credit card, or when you cancel a user's order before it is charged.</p> </li> <li><strong>android.test.refunded</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as - though the purchase was refunded. Refunds cannot be initiated through Android Market's in-app + <p>When you make an in-app billing request with this product ID, Google Play responds as + though the purchase was refunded. Refunds cannot be initiated through Google Play's in-app billing service. Refunds must be initiated by you (the merchant). After you process a refund request through your Google Checkout account, a refund message is sent to your application by - Android Market. This occurs only when Android Market gets notification from Google Checkout that + Google Play. This occurs only when Google Play gets notification from Google Checkout that a refund has been made. For more information about refunds, see <a href="{@docRoot}guide/market/billing/billing_overview.html#billing-action-notify">Handling IN_APP_NOTIFY messages</a> and <a @@ -100,7 +100,7 @@ reserved product IDs.</p> Pricing</a>.</p> </li> <li><strong>android.test.item_unavailable</strong> - <p>When you make an in-app billing request with this product ID, Android Market responds as + <p>When you make an in-app billing request with this product ID, Google Play responds as though the item being purchased was not listed in your application's product list.</p> </li> </ul> @@ -185,20 +185,20 @@ application's product list you use one of the reserved product IDs.</p> <p>You do not need to use a test account if you are testing only with the reserved product IDs.</p> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Run your application and purchase the reserved product IDs.</strong></li> </ol> <p class="note"><strong>Note</strong>: Making in-app billing requests with the reserved product IDs -overrides the usual Android Market production system. When you send an in-app billing request for a +overrides the usual Google Play production system. When you send an in-app billing request for a reserved product ID, the quality of service will not be comparable to the production environment.</p> @@ -207,7 +207,7 @@ environment.</p> <p>After you finish your static response testing, and you verify that signature verification is working in your application, you can test your in-app billing implementation by making actual in-app purchases. Testing real in-app purchases enables you to test the end-to-end in-app billing -experience, including the actual responses from Android Market and the actual checkout flow that +experience, including the actual responses from Google Play and the actual checkout flow that users will experience in your application.</p> <p class="note"><strong>Note</strong>: You do not need to publish your application to do end-to-end @@ -215,7 +215,7 @@ testing. You only need to upload your application as a draft application to perf testing.</p> <p>To test your in-app billing implementation with actual in-app purchases, you will need to -register at least one test account on the Android Market publisher site. You cannot use your +register at least one test account on the Google Play publisher site. You cannot use your developer account to test the complete in-app purchase process because Google Checkout does not let you buy items from yourself. If you have not set up test accounts before, see <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">Setting up test @@ -237,7 +237,7 @@ actual payouts to your merchant account.</p> IDs; you only need to upload your application as a draft application. However, you must sign your application with your release key before you upload it as a draft application. Also, the version number of the uploaded application must match the version number of the application you - load to your device for testing. To learn how to upload an application to Android Market, see + load to your device for testing. To learn how to upload an application to Google Play, see <a href="http://market.android.com/support/bin/answer.py?answer=113469">Uploading applications</a>.</p> </li> @@ -257,7 +257,7 @@ actual payouts to your merchant account.</p> <p>To perform end-to-end testing of in-app billing, the primary account on your device must be one of the <a href="{@docRoot}guide/market/billing/billing_admin.html#billing-testing-setup">test accounts</a> - that you registered on the Android Market site. If the primary account on your device is not a + that you registered on the Google Play site. If the primary account on your device is not a test account, you must do a factory reset of the device and then sign in with one of your test accounts. To perform a factory reset, do the following:</p> <ol> @@ -269,14 +269,14 @@ actual payouts to your merchant account.</p> device setup process.</li> </ol> </li> - <li><strong>Verify that your device is running a supported version of the Android Market + <li><strong>Verify that your device is running a supported version of the Google Play application or the MyApps application.</strong> <p>If your device is running Android 3.0, in-app billing requires version 5.0.12 (or higher) of the MyApps application. If your device is running any other version of Android, in-app billing - requires version 2.3.4 (or higher) of the Android Market application. To learn how to check the - version of the Android Market application, see <a - href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Android - Market</a>.</p> + requires version 2.3.4 (or higher) of the Google Play application. To learn how to check the + version of the Google Play application, see <a + href="http://market.android.com/support/bin/answer.py?answer=190860">Updating Google + Play</a>.</p> </li> <li><strong>Make in-app purchases in your application.</strong></li> </ol> @@ -285,7 +285,7 @@ actual payouts to your merchant account.</p> do a factory reset, making sure you log on with your primary account first.</p> <p>When you are finished testing your in-app billing implementation, you are ready to -publish your application on Android Market. You can follow the normal steps for <a +publish your application on Google Play. You can follow the normal steps for <a href="{@docRoot}guide/publishing/preparing.html">preparing</a>, <a href="{@docRoot}guide/publishing/app-signing.html">signing</a>, and <a href="{@docRoot}guide/publishing/publishing.html">publishing your application</a>. diff --git a/docs/html/guide/market/billing/index.jd b/docs/html/guide/market/billing/index.jd index fdfa6fa..036761f 100755 --- a/docs/html/guide/market/billing/index.jd +++ b/docs/html/guide/market/billing/index.jd @@ -30,18 +30,18 @@ page.title=In-app Billing </div> </div> -<p>Android Market In-app Billing is an Android Market service that lets you sell digital content in +<p>Google Play In-app Billing is a Google Play service that lets you sell digital content in your applications. You can use the service to sell a wide range of content, including downloadable content such as media files or photos, and virtual content such as game levels or potions.</p> -<p>When you use Android Market's in-app billing service to sell an item, Android Market handles all +<p>When you use Google Play's in-app billing service to sell an item, Google Play handles all checkout details so your application never has to directly process any financial transactions. -Android Market uses the same checkout service that is used for application purchases, so your users +Google Play uses the same checkout service that is used for application purchases, so your users experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for in-app purchases is the same as the transaction fee for application purchases (30%).</p> -<p>Any application that you publish through Android Market can implement in-app billing. No special -account or registration is required other than an Android Market publisher account and a Google +<p>Any application that you publish through Google Play can implement in-app billing. No special +account or registration is required other than a Google Play app publisher account and a Google Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add in-app billing to any application that uses a minimum API level of 4 or higher.</p> @@ -59,11 +59,11 @@ obfuscate the sample code before you use it in a production application. For mor <img src="{@docRoot}images/billing_checkout_flow.png" height="382" id="figure1" /> <p class="img-caption"> <strong>Figure 1.</strong> Applications initiate in-app billing requests through their own UI - (first screen). Android Market responds to the request by providing the checkout user interface + (first screen). Google Play responds to the request by providing the checkout user interface (middle screen). When checkout is complete, the application resumes. </p> -<p>To learn more about Android Market's in-app billing service and start integrating it into your +<p>To learn more about Google Play's in-app billing service and start integrating it into your applications, read the following documents:</p> <dl> @@ -88,7 +88,7 @@ applications, read the following documents:</p> <dd>Learn how to set up your product list, register test accounts, and handle refunds.</dd> <dt><strong><a href="{@docRoot}guide/market/billing/billing_reference.html">In-app Billing Reference</a></strong></dt> - <dd>Get detailed information about Android Market response codes and the in-app billing + <dd>Get detailed information about Google Play response codes and the in-app billing interface.</dd> </dl> diff --git a/docs/html/guide/market/expansion-files.jd b/docs/html/guide/market/expansion-files.jd new file mode 100644 index 0000000..36b8f9c --- /dev/null +++ b/docs/html/guide/market/expansion-files.jd @@ -0,0 +1,1270 @@ +page.title=APK Expansion Files +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> +<h2>Quickview</h2> +<ul> + <li>Recommended for most apps that exceed the 50MB APK limit</li> + <li>You can provide up to 4GB of additional data for each APK</li> + <li>Google Play hosts and serves the expansion files at no charge</li> + <li>The files can be any file type you want and are saved to the device's shared storage</li> +</ul> + +<h2>In this document</h2> +<ol> + <li><a href="#Overview">Overview</a> + <ol> + <li><a href="#Filename">File name format</a></li> + <li><a href="#StorageLocation">Storage location</a></li> + <li><a href="#DownloadProcess">Download process</a></li> + <li><a href="#Checklist">Development checklist</a></li> + </ol> + </li> + <li><a href="#Rules">Rules and Limitations</a></li> + <li><a href="#Downloading">Downloading the Expansion Files</a> + <ol> + <li><a href="#AboutLibraries">About the Downloader Library</a></li> + <li><a href="#Preparing">Preparing to use the Downloader Library</a></li> + <li><a href="#Permissions">Declaring user permissions</a></li> + <li><a href="#DownloaderService">Implementing the downloader service</a></li> + <li><a href="#AlarmReceiver">Implementing the alarm receiver</a></li> + <li><a href="#Download">Starting the download</a></li> + <li><a href="#Progress">Receiving download progress</a></li> + </ol> + </li> + <li><a href="#ExpansionPolicy">Using APKExpansionPolicy</a></li> + <li><a href="#ReadingTheFile">Reading the Expansion File</a> + <ol> + <li><a href="#GettingFilenames">Getting the file names</a></li> + <li><a href="#ZipLib">Using the APK Expansion Zip Library</a></li> + </ol> + </li> + <li><a href="#Testing">Testing Your Expansion Files</a> + <ol> + <li><a href="#TestingReading">Testing file reads</a></li> + <li><a href="#TestingReading">Testing file downloads</a></li> + </ol> + </li> + <li><a href="#Updating">Updating Your Application</a></li> +</ol> + +<h2>See also</h2> +<ol> + <li><a href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a></li> + <li><a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple +APK Support</a></li> +</ol> +</div> +</div> + + + +<p>Google Play currently requires that your APK file be no more than 50MB. For most +applications, this is plenty of space for all the application's code and assets. +However, some apps need more space for high-fidelity graphics, media files, or other large assets. +Previously, if your app exceeded 50MB, you had to host and download the additional resources +yourself when the user opens the app. Hosting and serving the extra files can be costly, and the +user experience is often less than ideal. To make this process easier for you and more pleasant +for users, Google Play allows you to attach two large expansion files that supplement your +APK.</p> + +<p>Google Play hosts the expansion files for your application and serves them to the device at +no cost to you. The expansion files are saved to the device's shared storage location (the +SD card or USB-mountable partition; also known as the "external" storage) where your app can access +them. On most devices, Google Play downloads the expansion file(s) at the same time it +downloads the APK, so your application has everything it needs when the user opens it for the +first time. In some cases, however, your application must download the files from Google Play +when your application starts.</p> + + + +<h2 id="Overview">Overview</h2> + +<p>Each time you upload an APK using the Google Play Android Developer Console, you have the option to +add one or two expansion files to the APK. Each file can be up to 2GB and it can be any format you +choose, but we recommend you use a compressed file to conserve bandwidth during the download. +Conceptually, each expansion file plays a different role:</p> + +<ul> + <li>The <strong>main</strong> expansion file is the +primary expansion file for additional resources required by your application.</li> + <li>The <strong>patch</strong> expansion file is optional and intended for small updates to the +main expansion file.</li> +</ul> + +<p>While you can use the two expansion files any way you wish, we recommend that the main +expansion file deliver the primary assets and should rarely if ever updated; the patch expansion +file should be smaller and serve as a “patch carrier,” getting updated with each major +release or as necessary.</p> + +<p>However, even if your application update requires only a new patch expansion file, you still must +upload a new APK with an updated <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code +versionCode}</a> in the manifest. (The +Developer Console does not allow you to upload an expansion file to an existing APK.)</p> + +<p class="note"><strong>Note:</strong> The patch expansion file is semantically the same as the +main expansion file—you can use each file any way you want. The system does +not use the patch expansion file to perform patching for your app. You must perform patching +yourself or be able to distinguish between the two files.</p> + + + +<h3 id="Filename">File name format</h3> + +<p>Each expansion file you upload can be any format you choose (ZIP, PDF, MP4, etc.). Regardless of +the file type, Google Play considers them opaque binary blobs and renames the files +using the following scheme:</p> + +<pre class="classic no-pretty-print"> +[main|patch].<expansion-version>.<package-name>.obb +</pre> + +<p>There are three components to this scheme:</p> + +<dl> + <dt>{@code main} or {@code patch}</dt> + <dd>Specifies whether the file is the main or patch expansion file. There can be +only one main file and one patch file for each APK.</dd> + <dt>{@code <expansion-version>}</dt> + <dd>This is an integer that matches the version code of the APK with which the expansion is +<em>first</em> associated (it matches the application's <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> +value). + <p>"First" is emphasized because although the Developer Console allows you to +re-use an uploaded expansion file with a new APK, the expansion file's name does not change—it +retains the version applied to it when you first uploaded the file.</p></dd> + <dt>{@code <package-name>}</dt> + <dd>Your application's Java-style package name.</dd> +</dl> + +<p>For example, suppose your APK version is 314159 and your package name is com.example.app. If you +upload a main expansion file, the file is renamed to:</p> +<pre class="classic no-pretty-print">main.314159.com.example.app.obb</pre> + + +<h3 id="StorageLocation">Storage location</h3> + +<p>When Google Play downloads your expansion files to a device, it saves them to the system's +shared storage location. To ensure proper behavior, you must not delete, move, or rename the +expansion files. In the event that your application must perform the download from Google Play +itself, you must save the files to the exact same location.</p> + +<p>The specific location for your expansion files is:</p> + +<pre class="classic no-pretty-print"> +<shared-storage>/Android/obb/<package-name>/ +</pre> + +<ul> + <li>{@code <shared-storage>} is the path to the shared storage space, available from +{@link android.os.Environment#getExternalStorageDirectory()}.</li> + <li>{@code <package-name>} is your application's Java-style package name, available +from {@link android.content.Context#getPackageName()}.</li> +</ul> + +<p>For each application, there are never more than two expansion files in this directory. +One is the main expansion file and the other is the patch expansion file (if necessary). Previous +versions are overwritten when you update your application with new expansion files.</p> + +<p>If you must unpack the contents of your expansion files, <strong>do not</strong> delete the +{@code .obb} expansion files afterwards and <strong>do not</strong> save the unpacked data +in the same directory. You should save your unpacked files in the directory +specified by {@link android.content.Context#getExternalFilesDir getExternalFilesDir()}. However, +if possible, it's best if you use an expansion file format that allows you to read directly from +the file instead of requiring you to unpack the data. For example, we've provided a library +project called the <a href="#ZipLib">APK Expansion Zip Library</a> that reads your data directly +from the ZIP file.</p> + +<p class="note"><strong>Note:</strong> Unlike APK files, any files saved on the shared storage can +be read by the user and other applications.</p> + +<p class="note"><strong>Tip:</strong> If you're packaging media files into a ZIP, you can use media +playback calls on the files with offset and length controls (such as {@link +android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and +{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}) without the +need to unpack your ZIP. In order for this to work, you must not perform additional compression on +the media files when creating the ZIP packages. For example, when using the <code>zip</code> tool, +you should use the <code>-n</code> option to specify the file suffixes that should not be +compressed: <br/> +<code>zip -n .mp4;.ogg main_expansion media_files</code></p> + + +<h3 id="DownloadProcess">Download process</h3> + +<p>Most of the time, Google Play downloads and saves your expansion files at the same time it +downloads the APK to the device. However, in some cases Google Play +cannot download the expansion files or the user might have deleted previously downloaded expansion +files. To handle these situations, your app must be able to download the files +itself when the main activity starts, using a URL provided by Google Play.</p> + +<p>The download process from a high level looks like this:</p> + +<ol> + <li>User selects to install your app from Google Play.</li> + <li>If Google Play is able to download the expansion files (which is the case for most +devices), it downloads them along with the APK. + <p>If Google Play is unable to download the expansion files, it downloads the +APK only.</p> + </li> + <li>When the user launches your application, your app must check whether the expansion files are +already saved on the device. + <ol> + <li>If yes, your app is ready to go.</li> + <li>If no, your app must download the expansion files over HTTP from Google Play. Your app +must send a request to the Google Play client using the Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service, which +responds with the name, file size, and URL for each expansion file. With this information, you then +download the files and save them to the proper <a href="#StorageLocation">storage location</a>.</li> + </ol> + </li> +</ol> + +<p class="caution"><strong>Caution:</strong> It is critical that you include the necessary code to +download the expansion files from Google Play in the event that the files are not already on the +device when your application starts. As discussed in the following section about <a +href="#Downloading">Downloading the Expansion Files</a>, we've made a library available to you that +greatly simplifies this process and performs the download from a service with a minimal amount of +code from you.</p> + + + + +<h3 id="Checklist">Development checklist</h3> + +<p>Here's a summary of the tasks you should perform to use expansion files with your +application:</p> + +<ol> + <li>First determine whether your application absolutely requires more than 50MB per installation. +Space is precious and you should keep your total application size as small as possible. If your app +uses more than 50MB in order to provide multiple versions of your graphic assets for multiple screen +densities, consider instead publishing <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> in which each APK +contains only the assets required for the screens that it targets.</li> + <li>Determine which application resources to separate from your APK and package them in a +file to use as the main expansion file. + <p>Normally, you should only use the second patch expansion file when performing updates to +the main expansion file. However, if your resources exceed the 2GB limit for the main +expansion file, you can use the patch file for the rest of your assets.</p> + </li> + <li>Develop your application such that it uses the resources from your expansion files in the +device's <a href="#StorageLocation">shared storage location</a>. + <p>Remember that you must not delete, move, or rename the expansion files.</p> + <p>If your application doesn't demand a specific format, we suggest you create ZIP files for +your expansion files, then read them using the <a href="#ZipLib">APK Expansion Zip +Library</a>.</p> + </li> + <li>Add logic to your application's main activity that checks whether the expansion files +are on the device upon start-up. If the files are not on the device, use Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service to request URLs +for the expansion files, then download and save them. + <p>To greatly reduce the amount of code you must write and ensure a good user experience +during the download, we recommend you use the <a href="AboutLibraries">Downloader +Library</a> to implement your download behavior.</p> + <p>If you build your own download service instead of using the library, be aware that you +must not change the name of the expansion files and must save them to the proper +<a href="#StorageLocation">storage location</a>.</p></li> +</ol> + +<p>Once you've finished your application development, follow the guide to <a href="#Testing">Testing +Your Expansion Files</a>.</p> + + + + + + +<h2 id="Rules">Rules and Limitations</h2> + +<p>Adding APK expansion files is a feature available when you upload your application using the +Developer Console. When uploading your application for the first time or updating an +application that uses expansion files, you must be aware of the following rules and limitations:</p> + +<ol type="I"> + <li>Each expansion file can be no more than 2GB.</li> + <li>In order to download your expansion files from Google Play, <strong>the user must have +acquired your application from Google Play</strong>. Google Play will not +provide the URLs for your expansion files if the application was installed by other means.</li> + <li>When performing the download from within your application, the URL that Google Play +provides for each file is unique for every download and each one expires shortly after it is given +to your application.</li> + <li>If you update your application with a new APK or upload <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> for the same +application, you can select expansion files that you've uploaded for a previous APK. <strong>The +expansion file's name does not change</strong>—it retains the version received by the APK to +which the file was originally associated.</li> + <li>If you use expansion files in combination with <a +href="{@docRoot}guide/market/publishing/multiple-apks.html">multiple APKs</a> in order to +provide different expansion files for different devices, you still must upload separate APKs +for each device in order to provide a unique <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> +value and declare different <a href="{@docRoot}guide/appendix/market-filters.html">filters</a> for +each APK.</li> + <li>You cannot issue an update to your application by changing the expansion files +alone—<strong>you must upload a new APK</strong> to update your app. If your changes only +concern the assets in your expansion files, you can update your APK simply by changing the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> (and +perhaps also the <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vname">{@code +versionName}</a>).</p></li> + <li><strong>Do not save other data into your <code>obb/</code> +directory</strong>. If you must unpack some data, save it into the location specified by {@link +android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> + <li><strong>Do not delete or rename the {@code .obb} expansion file</strong> (unless you're +performing an update). Doing so will cause Google Play (or your app itself) to repeatedly +download the expansion file.</li> + <li>When updating an expansion file manually, you must delete the previous expansion file.</li> +</ol> + + + + + + + + + +<h2 id="Downloading">Downloading the Expansion Files</h2> + +<p>In most cases, Google Play downloads and saves your expansion files to the device at the same +time it installs or updates the APK. This way, the expansion files are available when your +application launches for the first time. However, in some cases your app must download the +expansion files itself by requesting them from a URL provided to you in a response +from Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service.</p> + +<p>The basic logic you need to download your expansion files is the following:</p> + +<ol> + <li>When your application starts, look for the expansion files on the <a +href="#StorageLocation">shared storage location</a> (in the +<code>Android/obb/<package-name>/</code> directory). + <ol type="a"> + <li>If the expansion files are there, you're all set and your application can continue.</li> + <li>If the expansion files are <em>not</em> there: + <ol> + <li>Perform a request using Google Play's <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> to get your +app's expansion file names, sizes, and URLs.</li> + <li>Use the URLs provided by Google Play to download the expansion files and save +the expansion files. You <strong>must</strong> save the files to the <a +href="#StorageLocation">shared storage location</a> +(<code>Android/obb/<package-name>/</code>) and use the exact file name provided +by Google Play's response. + <p class="note"><strong>Note:</strong> The URL that Google Play provides for your +expansion files is unique for every download and each one expires shortly after it is given to +your application.</p> + </li> + </ol> + </li> + </ol> + </li> +</ol> + + +<p>If your application is free (not a paid app), then you probably haven't used the <a +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a> service. It's primarily +designed for you to enforce +licensing policies for your application and ensure that the user has the right to +use your app (he or she rightfully paid for it on Google Play). In order to facilitate the +expansion file functionality, the licensing service has been enhanced to provide a response +to your application that includes the URL of your application's expansion files that are hosted +on Google Play. So, even if your application is free for users, you need to include the +License Verification Library (LVL) to use APK expansion files. Of course, if your application +is free, you don't need to enforce license verification—you simply need the +library to perform the request that returns the URL of your expansion files.</p> + +<p class="note"><strong>Note:</strong> Whether your application is free or not, Google Play +returns the expansion file URLs only if the user acquired your application from Google Play.</p> + +<p>In addition to the LVL, you need a set of code that downloads the expansion files +over an HTTP connection and saves them to the proper location on the device's shared storage. +As you build this procedure into your application, there are several issues you should take into +consideration:</p> + +<ul> + <li>The device might not have enough space for the expansion files, so you should check +before beginning the download and warn the user if there's not enough space.</li> + <li>File downloads should occur in a background service in order to avoid blocking the user +interaction and allow the user to leave your app while the download completes.</li> + <li>A variety of errors might occur during the request and download that you must +gracefully handle.</li> + <li>Network connectivity can change during the download, so you should handle such changes and +if interrupted, resume the download when possible.</li> + <li>While the download occurs in the background, you should provide a notification that +indicates the download progress, notifies the user when it's done, and takes the user back to +your application when selected.</li> +</ul> + + +<p>To simplify this work for you, we've built the <a href="#AboutLibraries">Downloader Library</a>, +which requests the expansion file URLs through the licensing service, downloads the expansion files, +performs all of the tasks listed above, and even allows your activity to pause and resume the +download. By adding the Downloader Library and a few code hooks to your application, almost all the +work to download the expansion files is already coded for you. As such, in order to provide the best +user experience with minimal effort on your behalf, we recommend you use the Downloader Library to +download your expansion files. The information in the following sections explain how to integrate +the library into your application.</p> + +<p>If you'd rather develop your own solution to download the expansion files using the Google +Play URLs, you must follow the <a href="{@docRoot}guide/market/licensing/index.html">Application +Licensing</a> documentation to perform a license request, then retrieve the expansion file names, +sizes, and URLs from the response extras. You should use the <a href="#ExpansionPolicy">{@code +APKExpansionPolicy}</a> class (included in the License Verification Library) as your licensing +policy, which captures the expansion file names, sizes, and URLs from the licensing service..</p> + + + +<h3 id="AboutLibraries">About the Downloader Library</h3> + +<p>To use APK expansion files with your application and provide the best user experience with +minimal effort on your behalf, we recommend you use the Downloader Library that's included in the +Google Market Apk Expansion package. This library downloads your expansion files in a +background service, shows a user notification with the download status, handles network +connectivity loss, resumes the download when possible, and more.</p> + +<p>To implement expansion file downloads using the Downloader Library, all you need to do is:</p> + +<ul> + <li>Extend a special {@link android.app.Service} subclass and {@link +android.content.BroadcastReceiver} subclass that each require just a few +lines of code from you.</li> + <li>Add some logic to your main activity that checks whether the expansion files have +already been downloaded and, if not, invokes the download process and displays a +progress UI.</li> + <li>Implement a callback interface with a few methods in your main activity that +receives updates about the download progress.</li> +</ul> + +<p>The following sections explain how to set up your app using the Downloader Library.</p> + + +<h3 id="Preparing">Preparing to use the Downloader Library</h3> + +<p>To use the Downloader Library, you need to +download two packages from the SDK Manager and add the appropriate libraries to your +application.</p> + +<p>First, open the <a href="{@docRoot}sdk/adding-components.html">Android SDK Manager</a>, expand +<em>Extras</em> and download:</p> +<ul> + <li><em>Google Market Licensing package</em></li> + <li><em>Google Market Apk Expansion package</em></li> +</ul> + +<p>If you're using Eclipse, create a project for each library and add it to your app:</p> +<ol> + <li>Create a new Library Project for the License Verification Library and Downloader +Library. For each library: + <ol> + <li>Begin a new Android project.</li> + <li>Select <strong>Create project from existing +source</strong> and choose the library from the {@code <sdk>/extras/google/} directory +({@code market_licensing/} for the License Verification Library or {@code +market_apk_expansion/downloader_library/} for the Downloader Library).</li> + <li>Specify a <em>Project Name</em> such as "Google Play License Library" and "Google Play +Downloader +Library"</li> + <li>Click <strong>Finish</strong>.</li> + </ol> +<p class="note"><strong>Note:</strong> The Downloader Library depends on the License +Verification Library. Be sure to add the License +Verification Library to the Downloader Library's project properties (same process as +steps 2 and 3 below).</p> + </li> + <li>Right-click the Android project in which you want to use APK expansion files and +select <strong>Properties</strong>.</li> + <li>In the <em>Library</em> panel, click <strong>Add</strong> to select and add each of the +libraries to your application.</li> +</ol> + +<p>Or, from a command line, update your project to include the libraries:</p> +<ol> + <li>Change directories to the <code><sdk>/tools/</code> directory.</li> + <li>Execute <code>android update project</code> with the {@code --library} option to add both the +LVL and the Downloader Library to your project. For example: +<pre class="no-pretty-print"> +android update project --path ~/Android/MyApp \ +--library ~/android_sdk/extras/google/market_licensing \ +--library ~/android_sdk/extras/google/market_apk_expansion/downloader_library +</pre> + </li> +</ol> + +<p>With both the License Verification Library and Downloader Library added to your +application, you'll be able to quickly integrate the ability to download expansion files from +Google Play. The format that you choose for the expansion files and how you read them +from the shared storage is a separate implementation that you should consider based on your +application needs.</p> + +<p class="note"><strong>Tip:</strong> The Apk Expansion package includes a sample +application +that shows how to use the Downloader Library in an app. The sample uses a third library +available in the Apk Expansion package called the APK Expansion Zip Library. If +you plan on +using ZIP files for your expansion files, we suggest you also add the APK Expansion Zip Library to +your application. For more information, see the section below +about <a href="#ZipLib">Using the APK Expansion Zip Library</a>.</p> + + + +<h3 id="Permissions">Declaring user permissions</h3> + +<p>In order to download the expansion files, the Downloader Library +requires several permissions that you must declare in your application's manifest file. They +are:</p> + +<pre> +<manifest ...> + <!-- Required to access Google Play Licensing --> + <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> + + <!-- Required to download files from Google Play --> + <uses-permission android:name="android.permission.INTERNET" /> + + <!-- Required to keep CPU alive while downloading files (NOT to keep screen awake) --> + <uses-permission android:name="android.permission.WAKE_LOCK" /> + + <!-- Required to poll the state of the network connection and respond to changes --> + <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> + + <!-- Required to check whether Wi-Fi is enabled --> + <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/> + + <!-- Required to read and write the expansion files on shared storage --> + <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> + ... +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> By default, the Downloader Library requires API +level 4, but the APK Expansion Zip Library requires API level 5.</p> + + +<h3 id="DownloaderService">Implementing the downloader service</h3> + +<p>In order to perform downloads in the background, the Downloader Library provides its +own {@link android.app.Service} subclass called {@code DownloaderService} that you should extend. In +addition to downloading the expansion files for you, the {@code DownloaderService} also:</p> + +<ul> + <li>Registers a {@link android.content.BroadcastReceiver} that listens for changes to the +device's network connectivity (the {@link android.net.ConnectivityManager#CONNECTIVITY_ACTION} +broadcast) in order to pause the download when necessary (such as due to connectivity loss) and +resume the download when possible (connectivity is acquired).</li> + <li>Schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm to retry the download for +cases in which the service gets killed.</li> + <li>Builds a custom {@link android.app.Notification} that displays the download progress and +any errors or state changes.</li> + <li>Allows your application to manually pause and resume the download.</li> + <li>Verifies that the shared storage is mounted and available, that the files don't already exist, +and that there is enough space, all before downloading the expansion files. Then notifies the user +if any of these are not true.</li> +</ul> + +<p>All you need to do is create a class in your application that extends the {@code +DownloaderService} class and override three methods to provide specific application details:</p> + +<dl> + <dt>{@code getPublicKey()}</dt> + <dd>This must return a string that is the Base64-encoded RSA public key for your publisher +account, available from the profile page on the Developer Console (see <a +href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for Licensing</a>).</dd> + <dt>{@code getSALT()}</dt> + <dd>This must return an array of random bytes that the licensing {@code Policy} uses to +create an <a +href="{@docRoot}guide/market/licensing/adding-licensing.html#impl-Obfuscator">{@code +Obfuscator}</a>. The salt ensures that your obfuscated {@link android.content.SharedPreferences} +file in which your licensing data is saved will be unique and non-discoverable.</dd> + <dt>{@code getAlarmReceiverClassName()}</dt> + <dd>This must return the class name of the {@link android.content.BroadcastReceiver} in +your application that should receive the alarm indicating that the download should be +restarted (which might happen if the downloader service unexpectedly stops).</dd> +</dl> + +<p>For example, here's a complete implementation of {@code DownloaderService}:</p> + +<pre> +public class SampleDownloaderService extends DownloaderService { + // You must use the public key belonging to your publisher account + public static final String BASE64_PUBLIC_KEY = "YourLVLKey"; + // You should also modify this salt + public static final byte[] SALT = new byte[] { 1, 42, -12, -1, 54, 98, + -100, -12, 43, 2, -8, -4, 9, 5, -106, -107, -33, 45, -1, 84 + }; + + @Override + public String getPublicKey() { + return BASE64_PUBLIC_KEY; + } + + @Override + public byte[] getSALT() { + return SALT; + } + + @Override + public String getAlarmReceiverClassName() { + return SampleAlarmReceiver.class.getName(); + } +} +</pre> + +<p class="caution"><strong>Notice:</strong> You must update the {@code BASE64_PUBLIC_KEY} value +to be the public key belonging to your publisher account. You can find the key in the Developer +Console under your profile information. This is necessary even when testing +your downloads.</p> + +<p>Remember to declare the service in your manifest file:</p> +<pre> +<application ...> + <service android:name=".SampleDownloaderService" /> + ... +</application> +</pre> + + + +<h3 id="AlarmReceiver">Implementing the alarm receiver</h3> + +<p>In order to monitor the progress of the file downloads and restart the download if necessary, the +{@code DownloaderService} schedules an {@link android.app.AlarmManager#RTC_WAKEUP} alarm that +delivers an {@link android.content.Intent} to a {@link android.content.BroadcastReceiver} in your +application. You must define the {@link android.content.BroadcastReceiver} to call an API +from the Downloader Library that checks the status of the download and restarts +it if necessary.</p> + +<p>You simply need to override the {@link android.content.BroadcastReceiver#onReceive +onReceive()} method to call {@code +DownloaderClientMarshaller.startDownloadServiceIfRequired()}.</p> + +<p>For example:</p> + +<pre> +public class SampleAlarmReceiver extends BroadcastReceiver { + @Override + public void onReceive(Context context, Intent intent) { + try { + DownloaderClientMarshaller.startDownloadServiceIfRequired(context, intent, + SampleDownloaderService.class); + } catch (NameNotFoundException e) { + e.printStackTrace(); + } + } +} +</pre> + +<p>Notice that this is the class for which you must return the name +in your service's {@code getAlarmReceiverClassName()} method (see the previous section).</p> + +<p>Remember to declare the receiver in your manifest file:</p> +<pre> +<application ...> + <receiver android:name=".SampleAlarmReceiver" /> + ... +</application> +</pre> + + + +<h3 id="Download">Starting the download</h3> + +<p>The main activity in your application (the one started by your launcher icon) is +responsible for verifying whether the expansion files are already on the device and initiating +the download if they are not.</p> + +<p>Starting the download using the Downloader Library requires the following +procedures:</p> + +<ol> + <li>Check whether the files have been downloaded. + <p>The Downloader Library includes some APIs in the {@code Helper} class to +help with this process:</p> + <ul> + <li>{@code getExtendedAPKFileName(Context, c, boolean mainFile, int +versionCode)}</li> + <li>{@code doesFileExist(Context c, String fileName, long fileSize)}</li> + </ul> + <p>For example, the sample app provided in the Apk Expansion package calls the +following method in the activity's {@link android.app.Activity#onCreate onCreate()} method to check +whether the expansion files already exist on the device:</p> +<pre> +boolean expansionFilesDelivered() { + for (XAPKFile xf : xAPKS) { + String fileName = Helpers.getExpansionAPKFileName(this, xf.mIsBase, xf.mFileVersion); + if (!Helpers.doesFileExist(this, fileName, xf.mFileSize, false)) + return false; + } + return true; +} +</pre> + <p>In this case, each {@code XAPKFile} object holds the version number and file size of a known +expansion file and a boolean as to whether it's the main expansion file. (See the sample +application's {@code SampleDownloaderActivity} class for details.)</p> + <p>If this method returns false, then the application must begin the download.</p> + </li> + <li>Start the download by calling the static method {@code +DownloaderClientMarshaller.startDownloadServiceIfRequired(Context c, PendingIntent +notificationClient, Class<?> serviceClass)}. + <p>The method takes the following parameters:</p> + <ul> + <li><code>context</code>: Your application's {@link android.content.Context}.</li> + <li><code>notificationClient</code>: A {@link android.app.PendingIntent} to start your main +activity. This is used in the {@link android.app.Notification} that the {@code DownloaderService} +creates to show the download progress. When the user selects the notification, the system +invokes the {@link android.app.PendingIntent} you supply here and should open the activity +that shows the download progress (usually the same activity that started the download).</li> + <li><code>serviceClass</code>: The {@link java.lang.Class} object for your implementation of +{@code DownloaderService}, required to start the service and begin the download if necessary.</li> + </ul> + <p>The method returns an integer that indicates +whether or not the download is required. Possible values are:</p> + <ul> + <li>{@code NO_DOWNLOAD_REQUIRED}: Returned if the files already +exist or a download is already in progress.</li> + <li>{@code LVL_CHECK_REQUIRED}: Returned if a license verification is +required in order to acquire the expansion file URLs.</li> + <li>{@code DOWNLOAD_REQUIRED}: Returned if the expansion file URLs are already known, +but have not been downloaded.</li> + </ul> + <p>The behavior for {@code LVL_CHECK_REQUIRED} and {@code DOWNLOAD_REQUIRED} are essentially the +same and you normally don't need to be concerned about them. In your main activity that calls {@code +startDownloadServiceIfRequired()}, you can simply check whether or not the response is {@code +NO_DOWNLOAD_REQUIRED}. If the response is anything <em>other than</em> {@code NO_DOWNLOAD_REQUIRED}, +the Downloader Library begins the download and you should update your activity UI to +display the download progress (see the next step). If the response <em>is</em> {@code +NO_DOWNLOAD_REQUIRED}, then the files are available and your application can start.</p> + <p>For example:</p> +<pre> +@Override +public void onCreate(Bundle savedInstanceState) { + // Check if expansion files are available before going any further + if (!expansionFilesDelivered()) { + // Build an Intent to start this activity from the Notification + Intent notifierIntent = new Intent(this, MainActivity.getClass()); + notifierIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK | + Intent.FLAG_ACTIVITY_CLEAR_TOP); + ... + PendingIntent pendingIntent = PendingIntent.getActivity(this, 0, + notifierIntent, PendingIntent.FLAG_UPDATE_CURRENT); + + // Start the download service (if required) + int startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(this, + pendingIntent, SampleDownloaderService.class); + // If download has started, initialize this activity to show download progress + if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { + // This is where you do set up to display the download progress (next step) + ... + return; + } // If the download wasn't necessary, fall through to start the app + } + startApp(); // Expansion files are available, start the app +} +</pre> + </li> + <li>When the {@code startDownloadServiceIfRequired()} method returns anything <em>other +than</em> {@code NO_DOWNLOAD_REQUIRED}, create an instance of {@code IStub} by +calling {@code DownloaderClientMarshaller.CreateStub(IDownloaderClient client, Class<?> +downloaderService)}. The {@code IStub} provides a binding between your activity to the downloader +service such that your activity receives callbacks about the download progress. + <p>In order to instantiate your {@code IStub} by calling {@code CreateStub()}, you must pass it +an implementation of the {@code IDownloaderClient} interface and your {@code DownloaderService} +implementation. The next section about <a href="#Progress">Receiving download progress</a> discusses +the {@code IDownloaderClient} interface, which you should usually implement in your {@link +android.app.Activity} class so you can update the activity UI when the download state changes.</p> + <p>We recommend that you call {@code +CreateStub()} to instantiate your {@code IStub} during your activity's {@link +android.app.Activity#onCreate onCreate()} method, after {@code startDownloadServiceIfRequired()} +starts the download. </p> + <p>For example, in the previous code sample for {@link android.app.Activity#onCreate +onCreate()}, you can respond to the {@code startDownloadServiceIfRequired()} result like this:</p> +<pre> + // Start the download service (if required) + int startResult = DownloaderClientMarshaller.startDownloadServiceIfRequired(this, + pendingIntent, SampleDownloaderService.class); + // If download has started, initialize activity to show progress + if (startResult != DownloaderClientMarshaller.NO_DOWNLOAD_REQUIRED) { + // Instantiate a member instance of IStub + mDownloaderClientStub = DownloaderClientMarshaller.CreateStub(this, + SampleDownloaderService.class); + // Inflate layout that shows download progress + setContentView(R.layout.downloader_ui); + return; + } +</pre> + + <p>After the {@link android.app.Activity#onCreate onCreate()} method returns, your activity +receives a call to {@link android.app.Activity#onResume onResume()}, which is where you should then +call {@code connect()} on the {@code IStub}, passing it your application's {@link +android.content.Context}. Conversely, you should call +{@code disconnect()} in your activity's {@link android.app.Activity#onStop onStop()} callback.</p> +<pre> +@Override +protected void onResume() { + if (null != mDownloaderClientStub) { + mDownloaderClientStub.connect(this); + } + super.onResume(); +} + +@Override +protected void onStop() { + if (null != mDownloaderClientStub) { + mDownloaderClientStub.disconnect(this); + } + super.onStop(); +} +</pre> + <p>Calling {@code connect()} on the {@code IStub} binds your activity to the {@code +DownloaderService} such that your activity receives callbacks regarding changes to the download +state through the {@code IDownloaderClient} interface.</p> + </li> +</ol> + + + +<h3 id="Progress">Receiving download progress</h3> + +<p>To receive updates regarding the download progress and to interact with the {@code +DownloaderService}, you must implement the Downloader Library's {@code IDownloaderClient} interface. +Usually, the activity you use to start the download should implement this interface in order to +display the download progress and send requests to the service.</p> + +<p>The required interface methods for {@code IDownloaderClient} are:</p> + +<dl> + <dt>{@code onServiceConnected(Messenger m)}</dt> + <dd>After you instantiate the {@code IStub} in your activity, you'll receive a call to this +method, which passes a {@link android.os.Messenger} object that's connected with your instance +of {@code DownloaderService}. To send requests to the service, such as to pause and resume +downloads, you must call {@code DownloaderServiceMarshaller.CreateProxy()} to receive the {@code +IDownloaderService} interface connected to the service. + <p>A recommended implementation looks like this:</p> +<pre> +private IDownloaderService mRemoteService; +... + +@Override +public void onServiceConnected(Messenger m) { + mRemoteService = DownloaderServiceMarshaller.CreateProxy(m); + mRemoteService.onClientUpdated(mDownloaderClientStub.getMessenger()); +} +</pre> + <p>With the {@code IDownloaderService} object initialized, you can send commands to the +downloader service, such as to pause and resume the download ({@code requestPauseDownload()} +and {@code requestContinueDownload()}).</p> +</dd> + <dt>{@code onDownloadStateChanged(int newState)}</dt> + <dd>The download service calls this when a change in download state occurs, such as the +download begins or completes. + <p>The <code>newState</code> value will be one of several possible values specified in +by one of the {@code IDownloaderClient} class's {@code STATE_*} constants.</p> + <p>To provide a useful message to your users, you can request a corresponding string +for each state by calling {@code Helpers.getDownloaderStringResourceIDFromState()}. This +returns the resource ID for one of the strings bundled with the Downloader +Library. For example, the string "Download paused because you are roaming" corresponds to {@code +STATE_PAUSED_ROAMING}.</p></dd> + <dt>{@code onDownloadProgress(DownloadProgressInfo progress)}</dt> + <dd>The download service calls this to deliver a {@code DownloadProgressInfo} object, +which describes various information about the download progress, including estimated time remaining, +current speed, overall progress, and total so you can update the download progress UI.</dd> +</dl> +<p class="note"><strong>Tip:</strong> For examples of these callbacks that update the download +progress UI, see the {@code SampleDownloaderActivity} in the sample app provided with the +Apk Expansion package.</p> + +<p>Some public methods for the {@code IDownloaderService} interface you might find useful are:</p> + +<dl> + <dt>{@code requestPauseDownload()}</dt> + <dd>Pauses the download.</dd> + <dt>{@code requestContinueDownload()}</dt> + <dd>Resumes a paused download.</dd> + <dt>{@code setDownloadFlags(int flags)}</dt> + <dd>Sets user preferences for network types on which its OK to download the files. The +current implementation supports one flag, {@code FLAGS_DOWNLOAD_OVER_CELLULAR}, but you can add +others. By default, this flag is <em>not</em> enabled, so the user must be on Wi-Fi to download +expansion files. You might want to provide a user preference to enable downloads over +the cellular network. In which case, you can call: +<pre> +mRemoteService.setDownloadFlags(IDownloaderService.FLAGS_DOWNLOAD_OVER_CELLULAR); +</pre> +</dd> +</dl> + + + + +<h2 id="ExpansionPolicy">Using APKExpansionPolicy</h2> + +<p>If you decide to build your own downloader service instead of using the Google Play +<a href="#AboutLibraries">Downloader Library</a>, you should still use the {@code +APKExpansionPolicy} that's provided in the License Verification Library. The {@code +APKExpansionPolicy} class is nearly identical to {@code ServerManagedPolicy} (available in the +Google Play License Verification Library) but includes additional handling for the APK expansion +file response extras.</p> + +<p class="note"><strong>Note:</strong> If you <em>do use</em> the <a +href="#AboutLibraries">Downloader Library</a> as discussed in the previous section, the +library performs all interaction with the {@code APKExpansionPolicy} so you don't have to use +this class directly.</p> + +<p>The class includes methods to help you get the necessary information about the available +expansion files:</p> + +<ul> + <li>{@code getExpansionURLCount()}</li> + <li>{@code getExpansionURL(int index)}</li> + <li>{@code getExpansionFileName(int index)}</li> + <li>{@code getExpansionFileSize(int index)}</li> +</ul> + +<p>For more information about how to use the {@code APKExpansionPolicy} when you're <em>not</em> +using the <a +href="#AboutLibraries">Downloader Library</a>, see the documentation for <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding Licensing to Your App</a>, +which explains how to implement a license policy such as this one.</p> + + + + + + + +<h2 id="ReadingTheFile">Reading the Expansion File</h2> + +<p>Once your APK expansion files are saved on the device, how you read your files +depends on the type of file you've used. As discussed in the <a href="#Overview">overview</a>, your +expansion files can be any kind of file you +want, but are renamed using a particular <a href="#Filename">file name format</a> and are saved to +{@code <shared-storage>/Android/obb/<package-name>/}.</p> + +<p>Regardless of how you read your files, you should always first check that the external +storage is available for reading. There's a chance that the user has the storage mounted to a +computer over USB or has actually removed the SD card.</p> + +<p class="note"><strong>Note:</strong> When your application starts, you should always check whether +the external storage space is available and readable by calling {@link +android.os.Environment#getExternalStorageState()}. This returns one of several possible strings +that represent the state of the external storage. In order for it to be readable by your +application, the return value must be {@link android.os.Environment#MEDIA_MOUNTED}.</p> + + +<h3 id="GettingFilenames">Getting the file names</h3> + +<p>As described in the <a href="#Overview">overview</a>, your APK expansion files are saved +using a specific file name format:</p> + +<pre class="classic no-pretty-print"> +[main|patch].<expansion-version>.<package-name>.obb +</pre> + +<p>To get the location and names of your expansion files, you should use the +{@link android.os.Environment#getExternalStorageDirectory()} and {@link +android.content.Context#getPackageName()} methods to construct the path to your files.</p> + +<p>Here's a method you can use in your application to get an array containing the complete path +to both your expansion files:</p> + +<pre> +// The shared path to all app expansion files +private final static String EXP_PATH = "/Android/obb/"; + +static String[] getAPKExpansionFiles(Context ctx, int mainVersion, int patchVersion) { + String packageName = ctx.getPackageName(); + Vector<String> ret = new Vector<String>(); + if (Environment.getExternalStorageState().equals(Environment.MEDIA_MOUNTED)) { + // Build the full path to the app's expansion files + File root = Environment.getExternalStorageDirectory(); + File expPath = new File(root.toString() + EXP_PATH + packageName); + + // Check that expansion file path exists + if (expPath.exists()) { + if ( mainVersion > 0 ) { + String strMainPath = expPath + File.separator + "main." + + mainVersion + "." + packageName + ".obb"; + File main = new File(strMainPath); + if ( main.isFile() ) { + ret.add(strMainPath); + } + } + if ( patchVersion > 0 ) { + String strPatchPath = expPath + File.separator + "patch." + + mainVersion + "." + packageName + ".obb"; + File main = new File(strPatchPath); + if ( main.isFile() ) { + ret.add(strPatchPath); + } + } + } + } + String[] retArray = new String[ret.size()]; + ret.toArray(retArray); + return retArray; +} +</pre> + +<p>You can call this method by passing it your application {@link android.content.Context} +and the desired expansion file's version.</p> + +<p>There are many ways you could determine the expansion file version number. One simple way is to +save the version in a {@link android.content.SharedPreferences} file when the download begins, by +querying the expansion file name with the {@code APKExpansionPolicy} class's {@code +getExpansionFileName(int index)} method. You can then get the version code by reading the {@link +android.content.SharedPreferences} file when you want to access the expansion +file.</p> + +<p>For more information about reading from the shared storage, see the <a +href="{@docRoot}guide/topics/data/data-storage.html#filesExternal">Data Storage</a> +documentation.</p> + + + +<h3 id="ZipLib">Using the APK Expansion Zip Library</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> + <h3>Reading media files from a ZIP</h3> + <p>If you're using your expansion files to store media files, a ZIP file still allows you to +use Android media playback calls that provide offset and length controls (such as {@link +android.media.MediaPlayer#setDataSource(FileDescriptor,long,long) MediaPlayer.setDataSource()} and +{@link android.media.SoundPool#load(FileDescriptor,long,long,int) SoundPool.load()}). In order for +this to work, you must not perform additional compression on the media files when creating the ZIP +packages. For example, when using the <code>zip</code> tool, you should use the <code>-n</code> +option to specify the file suffixes that should not be compressed:</p> +<p><code>zip -n .mp4;.ogg main_expansion media_files</code></p> +</div> +</div> + +<p>The Google Market Apk Expansion package includes a library called the APK +Expansion Zip Library (located in {@code +<sdk>/extras/google/google_market_apk_expansion/zip_file/}). This is an optional library that +helps you read your expansion +files when they're saved as ZIP files. Using this library allows you to easily read resources from +your ZIP expansion files as a virtual file system.</p> + +<p>The APK Expansion Zip Library includes the following classes and APIs:</p> + +<dl> + <dt>{@code APKExpansionSupport}</dt> + <dd>Provides some methods to access expansion file names and ZIP files: + + <dl style="margin-top:1em"> + <dt>{@code getAPKExpansionFiles()}</dt> + <dd>The same method shown above that returns the complete file path to both expansion +files.</dd> + <dt>{@code getAPKExpansionZipFile(Context ctx, int mainVersion, int +patchVersion)}</dt> + <dd>Returns a {@code ZipResourceFile} representing the sum of both the main file and +patch file. That is, if you specify both the <code>mainVersion</code> and the +<code>patchVersion</code>, this returns a {@code ZipResourceFile} that provides read access to +all the data, with the patch file's data merged on top of the main file.</dd> + </dl> + </dd> + + <dt>{@code ZipResourceFile}</dt> + <dd>Represents a ZIP file on the shared storage and performs all the work to provide a virtual +file system based on your ZIP files. You can get an instance using {@code +APKExpansionSupport.getAPKExpansionZipFile()} or with the {@code ZipResourceFile} by passing it the +path to your expansion file. This class includes a variety of useful methods, but you generally +don't need to access most of them. A couple of important methods are: + + <dl style="margin-top:1em"> + <dt>{@code getInputStream(String assetPath)}</dt> + <dd>Provides an {@link java.io.InputStream} to read a file within the ZIP file. The +<code>assetPath</code> must be the path to the desired file, relative to +the root of the ZIP file contents.</dd> + <dt>{@code getAssetFileDescriptor(String assetPath)}</dt> + <dd>Provides an {@link android.content.res.AssetFileDescriptor} for a file within the +ZIP file. The <code>assetPath</code> must be the path to the desired file, relative to +the root of the ZIP file contents. This is useful for certain Android APIs that require an {@link +android.content.res.AssetFileDescriptor}, such as some {@link android.media.MediaPlayer} APIs.</dd> + </dl> + </dd> + + <dt>{@code APEZProvider}</dt> + <dd>Most applications don't need to use this class. This class defines a {@link +android.content.ContentProvider} that marshals the data from the ZIP files through a content +provider {@link android.net.Uri} in order to provide file access for certain Android APIs that +expect {@link android.net.Uri} access to media files. For example, this is useful if you want to +play a video with {@link android.widget.VideoView#setVideoURI VideoView.setVideoURI()}.</p></dd> +</dl> + +<h4>Reading from a ZIP file</h4> + +<p>When using the APK Expansion Zip Library, reading a file from your ZIP usually requires the +following:</p> + +<pre> +// Get a ZipResourceFile representing a merger of both the main and patch files +ZipResourceFile expansionFile = APKExpansionSupport.getAPKExpansionZipFile(appContext, + mainVersion, patchVersion); + +// Get an input stream for a known file inside the expansion file ZIPs +InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); +</pre> + +<p>The above code provides access to any file that exists in either your main expansion file or +patch expansion file, by reading from a merged map of all the files from both files. All you +need to provide the {@code getAPKExpansionFile()} method is your application {@code +android.content.Context} and the version number for both the main expansion file and patch +expansion file.</p> + +<p>If you'd rather read from a specific expansion file, you can use the {@code +ZipResourceFile} constructor with the path to the desired expansion file:</p> + +<pre> +// Get a ZipResourceFile representing a specific expansion file +ZipResourceFile expansionFile = new ZipResourceFile(filePathToMyZip); + +// Get an input stream for a known file inside the expansion file ZIPs +InputStream fileStream = expansionFile.getInputStream(pathToFileInsideZip); +</pre> + +<p>For more information about using this library for your expansion files, look at +the sample application's {@code SampleDownloaderActivity} class, which includes additional code to +verify the downloaded files using CRC. Beware that if you use this sample as the basis for +your own implementation, it requires that you <strong>declare the byte size of your expansion +files</strong> in the {@code xAPKS} array.</p> + + + + +<h2 id="Testing">Testing Your Expansion Files</h2> + +<p>Before publishing your application, there are two things you should test: Reading the +expansion files and downloading the files.</p> + + +<h3 id="TestingReading">Testing file reads</h3> + +<p>Before you upload your application to Google Play, you +should test your application's ability to read the files from the shared storage. All you need to do +is add the files to the appropriate location on the device shared storage and launch your +application:</p> + +<ol> + <li>On your device, create the appropriate directory on the shared storage where Google +Play will save your files. + <p>For example, if your package name is {@code com.example.android}, you need to create +the directory {@code Android/obb/com.example.android/} on the shared storage space. (Plug in +your test device to your computer to mount the shared storage and manually create this +directory.)</p> + </li> + <li>Manually add the expansion files to that directory. Be sure that you rename your files to +match the <a href="#Filename">file name format</a> that Google Play will use. + <p>For example, regardless of the file type, the main expansion file for the {@code +com.example.android} application should be {@code main.0300110.com.example.android.obb}. +The version code can be whatever value you want. Just remember:</p> + <ul> + <li>The main expansion file always starts with {@code main} and the patch file starts with +{@code patch}.</li> + <li>The package name always matches that of the APK to which the file is attached on +Google Play. + </ul> + </li> + <li>Now that the expansion file(s) are on the device, you can install and run your application to +test your expansion file(s).</li> +</ol> + +<p>Here are some reminders about handling the expansion files:</p> +<ul> + <li><strong>Do not delete or rename</strong> the {@code .obb} expansion files (even if you unpack +the data to a different location). Doing so will cause Google Play (or your app itself) to +repeatedly download the expansion file.</li> + <li><strong>Do not save other data into your <code>obb/</code> +directory</strong>. If you must unpack some data, save it into the location specified by {@link +android.content.Context#getExternalFilesDir getExternalFilesDir()}.</li> +</ul> + + + +<h3 id="TestingReading">Testing file downloads</h3> + +<p>Because your application must sometimes manually download the expansion files when it first +opens, it's important that you test this process to be sure your application can successfully query +for the URLs, download the files, and save them to the device.</p> + +<p>To test your application's implementation of the manual download procedure, you must upload +your application to Google Play as a "draft" to make your expansion files available for +download:</p> + +<ol> + <li>Upload your APK and corresponding expansion files using the Google Play Developer +Console.</li> + <li>Fill in the necessary application details (title, screenshots, etc.). You can come back and +finalize these details before publishing your application. + <p>Click the <strong>Save</strong> button. <em>Do not click Publish.</em> This saves +the application as a draft, such that your application is not published for Google Play users, +but the expansion files are available for you to test the download process.</p></li> + <li>Install the application on your test device using the Eclipse tools or <a +href="{@docRoot}guide/developing/tools/adb.html">{@code adb}</a>.</li> + <li>Launch the app.</li> +</ol> + +<p>If everything works as expected, your application should begin downloading the expansion +files as soon as the main activity starts.</p> + + + + +<h2 id="Updating">Updating Your Application</h2> + +<p>One of the great benefits to using expansion files on Google Play is the ability to +update your application without re-downloading all of the original assets. Because Google Play +allows you to provide two expansion files with each APK, you can use the second file as a "patch" +that provides updates and new assets. Doing so avoids the +need to re-download the main expansion file which could be large and expensive for users.</p> + +<p>The patch expansion file is technically the same as the main expansion file and neither +the Android system nor Google Play perform actual patching between your main and patch expansion +files. Your application code must perform any necessary patches itself.</p> + +<p>If you use ZIP files as your expansion files, the <a href="#ZipLib">APK Expansion Zip +Library</a> that's included with the Apk Expansion package includes the ability to merge +your +patch file with the main expansion file.</p> + +<p class="note"><strong>Note:</strong> Even if you only need to make changes to the patch +expansion file, you must still update the APK in order for Google Play to perform an update. +If you don't require code changes in the application, you should simply update the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code versionCode}</a> in the +manifest.</p> + +<p>As long as you don't change the main expansion file that's associated with the APK +in the Developer Console, users who previously installed your application will not +download the main expansion file. Existing users receive only the updated APK and the new patch +expansion file (retaining the previous main expansion file).</p> + +<p>Here are a few issues to keep in mind regarding updates to expansion files:</p> + +<ul> + <li>There can be only two expansion files for your application at a time. One main expansion +file and one patch expansion file. During an update to a file, Google Play deletes the +previous version (and so must your application when performing manual updates).</li> + <li>When adding a patch expansion file, the Android system does not actually patch your +application or main expansion file. You must design your application to support the patch data. +However, the Apk Expansion package includes a library for using ZIP files +as expansion files, which merges the data from the patch file into the main expansion file so +you can easily read all the expansion file data.</li> +</ul> + + + +<!-- Tools are not ready. + +<h3>Using OBB tool and APIs</h3> + +<pre> +$ mkobb.sh -d /data/myfiles -k my_secret_key -o /data/data.obb +$ obbtool a -n com.example.myapp -v 1 -s seed_from_mkobb /data/data.obb +</pre> + +<pre> +storage = (StorageManager) getSystemService( STORAGE_SERVICE ); +storage.mountObb( obbFilepath, "my_secret_key", myListener ); +obbContentPath = storage.getMountedObbPath( obbFilepath ); +</pre> +--> diff --git a/docs/html/guide/market/licensing/adding-licensing.jd b/docs/html/guide/market/licensing/adding-licensing.jd new file mode 100644 index 0000000..d4dd008 --- /dev/null +++ b/docs/html/guide/market/licensing/adding-licensing.jd @@ -0,0 +1,1072 @@ +page.title=Adding Licensing to Your App +parent.title=Application Licensing +parent.link=index.html +@jd:body + + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#manifest-permission">Adding the Licensing Permission</a></li> + <li><a href="#impl-Policy">Implementing a Policy</a> + <ol> + <li><a href="#custom-policies">Guidelines for custom policies</a></li> + <li><a href="#ServerManagedPolicy">ServerManagedPolicy</a></li> + <li><a href="#StrictPolicy">StrictPolicy</a></li> + </ol> + </li> + <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a> + <ol> + <li><a href="#AESObfuscator">AESObfuscator</a></li> + </ol> + </li> + <li><a href="#impl-lc">Checking the License from an Activity</a> + <ol> + <li><a href="#lc-overview">Overview of license check and response</a></li> + <li><a href="#imports">Add imports</a></li> + <li><a href="#lc-impl">Implement LicenseCheckerCallback as a private inner class</a></li> + <li><a href="#thread-handler">Create a Handler for posting from LicenseCheckerCallback +to the UI thread</a></li> + <li><a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a></li> + <li><a href="#check-access">Call checkAccess() to initiate the license check</a></li> + <li><a href="#account-key">Embed your public key for licensing</a></li> + <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method +to close IPC connections</a></li> + </ol> + </li> + <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> + <li><a href="#app-obfuscation">Obfuscating Your Code</a></li> + <li><a href="#app-publishing">Publishing a Licensed Application</a> + <ol> + <li><a href="#">Removing Copy Protection</a></li> + </ol> + </li> + <li><a href="#support">Where to Get Support</a></li> +</ol> + +</div> +</div> + + + +<p>After you've set up a publisher account and development environment (see <a +href="setting-up.html">Setting Up for Licensing</a>), you are ready to add license verification to +your app with the License Verification Library (LVL).</p> + +<p>Adding license verification with the LVL involves these tasks:</p> + +<ol> +<li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> +<li><a href="#impl-Policy">Implementing a Policy</a> — you can choose one of the full implementations provided in the LVL or create your own.</li> +<li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your {@code Policy} will cache any +license response data. </li> +<li><a href="#impl-lc">Adding code to check the license</a> in your application's main +Activity.</li> +<li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for +most applications).</li> +</ol> + +<p>The sections below describe these tasks. When you are done with the +integration, you should be able to compile your application successfully and you +can begin testing, as described in <a +href="{@docRoot}guide/market/licensing/setting-up.html#test-env">Setting Up the Test +Environment</a>.</p> + +<p>For an overview of the full set of source files included in the LVL, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#lvl-summary">Summary of LVL Classes +and Interfaces</a>.</p> + + +<h2 id="manifest-permission">Adding the Licensing Permission</h2> + +<p>To use the Google Play application for sending a license check to the +server, your application must request the proper permission, +<code>com.android.vending.CHECK_LICENSE</code>. If your application does +not declare the licensing permission but attempts to initiate a license check, +the LVL throws a security exception.</p> + +<p>To request the licensing permission in your application, declare a <a +href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> +element as a child of <code><manifest></code>, as follows: </p> + +<p style="margin-left:2em;"><code><uses-permission +android:name="com.android.vending.CHECK_LICENSE"></code></p> + +<p>For example, here's how the LVL sample application declares the permission: +</p> + +<pre><?xml version="1.0" encoding="utf-8"?> + +<manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> + <!-- Devices >= 3 have version of Google Play that supports licensing. --> + <uses-sdk android:minSdkVersion="3" /> + <!-- Required permission to check licensing. --> + <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> + ... +</manifest> +</pre> + +<p class="note"><strong>Note:</strong> Currently, you cannot declare the +<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, +because the SDK Tools will not merge it into the manifests of dependent +applications. Instead, you must declare the permission in each dependent +application's manifest. </p> + + +<h2 id="impl-Policy">Implementing a Policy</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>ServerManagedPolicy</h2> + +<p>The LVL includes a complete {@code Policy} implementation called ServerManagedPolicy +that makes use of license-management settings provided by the Google Play +server. </p> + +<p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your +Policy is strongly recommended. For more information, see <a +href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> + +</div> +</div> + +<p>Google Play licensing service does not itself determine whether a +given user with a given license should be granted access to your application. +Rather, that responsibility is left to a {@code Policy} implementation that you provide +in your application.</p> + +<p>Policy is an interface declared by the LVL that is designed to hold your +application's logic for allowing or disallowing user access, based on the result +of a license check. To use the LVL, your application <em>must</em> provide an +implementation of {@code Policy}. </p> + +<p>The {@code Policy} interface declares two methods, <code>allowAccess()</code> and +<code>processServerResponse()</code>, which are called by a {@code LicenseChecker} +instance when processing a response from the license server. It also declares an +enum called <code>LicenseResponse</code>, which specifies the license response +value passed in calls to <code>processServerResponse()</code>. </p> + +<ul> +<li><code>processServerResponse()</code> lets you preprocess the raw response +data received from the licensing server, prior to determining whether to grant +access. + +<p>A typical implementation would extract some or all fields from the license +response and store the data locally to a persistent store, such as through +{@link android.content.SharedPreferences} storage, to ensure that the data is +accessible across application invocations and device power cycles. For example, +a {@code Policy} would maintain the timestamp of the last successful license check, the +retry count, the license validity period, and similar information in a +persistent store, rather than resetting the values each time the application is +launched.</p> + +<p>When storing response data locally, the {@code Policy} must ensure that the data is +obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, +below).</p></li> + +<li><code>allowAccess()</code> determines whether to grant the user access to +your application, based on any available license response data (from the +licensing server or from cache) or other application-specific information. For +example, your implementation of <code>allowAccess()</code> could take into +account additional criteria, such as usage or other data retrieved from a +backend server. In all cases, an implementation of <code>allowAccess()</code> +should only return <code>true</code> if the user is licensed to use the +application, as determined by the licensing server, or if there is a transient +network or system problem that prevents the license check from completing. In +such cases, your implementation can maintain a count of retry responses and +provisionally allow access until the next license check is complete.</li> + +</ul> + +<p>To simplify the process of adding licensing to your application and to +provide an illustration of how a {@code Policy} should be designed, the LVL includes +two full {@code Policy} implementations that you can use without modification or +adapt to your needs:</p> + +<ul> +<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible {@code Policy} +that uses server-provided settings and cached responses to manage access across +varied network conditions, and</li> +<li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response +data and allows access <em>only</em> if the server returns a licensed +response.</li> +</ul> + +<p>For most applications, the use of ServerManagedPolicy is highly +recommended. ServerManagedPolicy is the LVL default and is integrated with +the LVL sample application.</p> + + +<h3 id="custom-policies">Guidelines for custom policies</h3> + +<p>In your licensing implementation, you can use one of the complete policies +provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a +custom policy. For any type of custom policy, there are several important design +points to understand and account for in your implementation.</p> + +<p>The licensing server applies general request limits to guard against overuse +of resources that could result in denial of service. When an application exceeds +the request limit, the licensing server returns a 503 response, which gets +passed through to your application as a general server error. This means that no +license response will be available to the user until the limit is reset, which +can affect the user for an indefinite period.</p> + +<p>If you are designing a custom policy, we recommend that the {@code Policy}: +<ol> +<!-- <li>Limits the number of points at which your app calls for a license check +to the minimum. </li> --> +<li>Caches (and properly obfuscates) the most recent successful license response +in local persistent storage.</li> +<li>Returns the cached response for all license checks, for as long as the +cached response is valid, rather than making a request to the licensing server. +Setting the response validity according to the server-provided <code>VT</code> +extra is highly recommended. See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response Extras</a> +for more information.</li> +<li>Uses an exponential backoff period, if retrying any requests the result in +errors. Note that the Google Play client automatically retries failed +requests, so in most cases there is no need for your {@code Policy} to retry them.</li> +<li>Provides for a "grace period" that allows the user to access your +application for a limited time or number of uses, while a license check is being +retried. The grace period benefits the user by allowing access until the next +license check can be completed successfully and it benefits you by placing a +hard limit on access to your application when there is no valid license response +available.</li> +</ol> + +<p>Designing your {@code Policy} according to the guidelines listed above is critical, +because it ensures the best possible experience for users while giving you +effective control over your application even in error conditions. </p> + +<p>Note that any {@code Policy} can use settings provided by the licensing server to +help manage validity and caching, retry grace period, and more. Extracting the +server-provided settings is straightforward and making use of them is highly +recommended. See the ServerManagedPolicy implementation for an example of how to +extract and use the extras. For a list of server settings and information about +how to use them, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response +Extras</a>.</p> + +<h3 id="ServerManagedPolicy">ServerManagedPolicy</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Server Response Extras</h2> + +<p>For certain types of licensing responses, the licensing server appends extra +settings to the responses, to help the application manage licensing effectively. +</p> + +<p style="margin-top:.5em;">See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response Extras</a> +for +a list of settings and <code>ServerManagedPolicy.java</code> for information +about how a {@code Policy} can use the extras.</p> + +</div> +</div> + +<p>The LVL includes a full and recommended implementation of the {@code Policy} +interface called ServerManagedPolicy. The implementation is integrated with the +LVL classes and serves as the default {@code Policy} in the library. </p> + +<p>ServerManagedPolicy provides all of the handling for license and retry +responses. It caches all of the response data locally in a +{@link android.content.SharedPreferences} file, obfuscating it with the +application's {@code Obfuscator} implementation. This ensures that the license response +data is secure and persists across device power cycles. ServerManagedPolicy +provides concrete implementations of the interface methods +<code>processServerResponse()</code> and <code>allowAccess()</code> and also +includes a set of supporting methods and types for managing license +responses.</p> + +<p>Importantly, a key feature of ServerMangedPolicy is its use of +server-provided settings as the basis for managing licensing across an +application's refund period and through varying network and error conditions. +When an application contacts the Google Play server for a license check, the +server appends several settings as key-value pairs in the extras field of certain +license response types. For example, the server provides recommended values for the +application's license validity period, retry grace period, and maximum allowable +retry count, among others. ServerManagedPolicy extracts the values from the +license response in its <code>processServerResponse()</code> method and checks +them in its <code>allowAccess()</code> method. For a list of the server-provided +settings used by ServerManagedPolicy, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#extras">Server Response +Extras</a>.</p> + +<p>For convenience, best performance, and the benefit of using license settings +from the Google Play server, <strong>using ServerManagedPolicy as your +licensing {@code Policy} is strongly recommended</strong>. </p> + +<p>If you are concerned about the security of license response data that is +stored locally in {@link android.content.SharedPreferences}, you can use a stronger obfuscation +algorithm or design a stricter {@code Policy} that does not store license data. The LVL +includes an example of such a {@code Policy} — see <a +href="#StrictPolicy">StrictPolicy</a> for more information.</p> + +<p>To use ServerManagedPolicy, simply import it to your Activity, create an +instance, and pass a reference to the instance when constructing your +{@code LicenseChecker}. See <a href="#lc-lcc">Instantiate LicenseChecker and +LicenseCheckerCallback</a> for more information. </p> + +<h3 id="StrictPolicy">StrictPolicy</h3> + +<p>The LVL includes an alternative full implementation of the {@code Policy} interface +called StrictPolicy. The StrictPolicy implementation provides a more restrictive +Policy than ServerManagedPolicy, in that it does not allow the user to access +the application unless a license response is received from the server at the +time of access that indicates that the user is licensed.</p> + +<p>The principal feature of StrictPolicy is that it does not store <em>any</em> +license response data locally, in a persistent store. Because no data is stored, +retry requests are not tracked and cached responses can not be used to fulfill +license checks. The {@code Policy} allows access only if:</p> + +<ul> +<li>The license response is received from the licensing server, and </li> +<li>The license response indicates that the user is licensed to access the +application. </li> +</ul> + +<p>Using StrictPolicy is appropriate if your primary concern is to ensure that, +in all possible cases, no user will be allowed to access the application unless +the user is confirmed to be licensed at the time of use. Additionally, the +Policy offers slightly more security than ServerManagedPolicy — since +there is no data cached locally, there is no way a malicious user could tamper +with the cached data and obtain access to the application.</p> + +<p>At the same time, this {@code Policy} presents a challenge for normal users, since it +means that they won't be able to access the application when there is no network +(cell or Wi-Fi) connection available. Another side-effect is that your +application will send more license check requests to the server, since using a +cached response is not possible.</p> + +<p>Overall, this policy represents a tradeoff of some degree of user convenience +for absolute security and control over access. Consider the tradeoff carefully +before using this {@code Policy}.</p> + +<p>To use StrictPolicy, simply import it to your Activity, create an instance, +and pass a reference to it when constructing your {@code LicenseChecker}. See +<a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> +for more information. </p> + +<h2 id="impl-Obfuscator">Implementing an Obfuscator</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>AESObfuscator</h2> + +<p>The LVL includes a full {@code Obfuscator} implementation in the +<code>AESObfuscator.java</code> file. The {@code Obfuscator} uses AES encryption to +obfuscate/unobfuscate data. If you are using a {@code Policy} (such as +ServerManagedPolicy) that caches license response data, using AESObfuscator as +basis for your {@code Obfuscator} implementation is highly recommended. </p> + +</div> +</div> + +<p>A typical {@code Policy} implementation needs to save the license response data for +an application to a persistent store, so that it is accessible across +application invocations and device power cycles. For example, a {@code Policy} would +maintain the timestamp of the last successful license check, the retry count, +the license validity period, and similar information in a persistent store, +rather than resetting the values each time the application is launched. The +default {@code Policy} included in the LVL, ServerManagedPolicy, stores license response +data in a {@link android.content.SharedPreferences} instance, to ensure that the +data is persistent. </p> + +<p>Because the {@code Policy} will use stored license response data to determine whether +to allow or disallow access to the application, it <em>must</em> ensure that any +stored data is secure and cannot be reused or manipulated by a root user on a +device. Specifically, the {@code Policy} must always obfuscate the data before storing +it, using a key that is unique for the application and device. Obfuscating using +a key that is both application-specific and device-specific is critical, because +it prevents the obfuscated data from being shared among applications and +devices.</p> + +<p>The LVL assists the application with storing its license response data in a +secure, persistent manner. First, it provides an {@code Obfuscator} +interface that lets your application supply the obfuscation algorithm of its +choice for stored data. Building on that, the LVL provides the helper class +PreferenceObfuscator, which handles most of the work of calling the +application's {@code Obfuscator} class and reading and writing the obfuscated data in a +{@link android.content.SharedPreferences} instance. </p> + +<p>The LVL provides a full {@code Obfuscator} implementation called +AESObfuscator that uses AES encryption to obfuscate data. You can +use AESObfuscator in your application without modification or you +can adapt it to your needs. For more information, see the next section.</p> + + +<h3 id="AESObfuscator">AESObfuscator</h3> + +<p>The LVL includes a full and recommended implementation of the {@code Obfuscator} +interface called AESObfuscator. The implementation is integrated with the +LVL sample application and serves as the default {@code Obfuscator} in the library. </p> + +<p>AESObfuscator provides secure obfuscation of data by using AES to +encrypt and decrypt the data as it is written to or read from storage. +The {@code Obfuscator} seeds the encryption using three data fields provided +by the application: </p> + +<ol> +<li>A salt — an array of random bytes to use for each (un)obfuscation. </li> +<li>An application identifier string, typically the package name of the application.</li> +<li>A device identifier string, derived from as many device-specific sources +as possible, so as to make it as unique.</li> +</ol> + +<p>To use AESObfuscator, first import it to your Activity. Declare a private +static final array to hold the salt bytes and initialize it to 20 randomly +generated bytes.</p> + +<pre> ... + // Generate 20 random bytes, and put them here. + private static final byte[] SALT = new byte[] { + -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, + -45, 77, -117, -36, -113, -11, 32, -64, 89 + }; + ... +</pre> + +<p>Next, declare a variable to hold a device identifier and generate a value for +it in any way needed. For example, the sample application included in the LVL +queries the system settings for the +<code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. +</p> + +<p>Note that, depending on the APIs you use, your application might need to +request additional permissions in order to acquire device-specific information. +For example, to query the {@link android.telephony.TelephonyManager} to obtain +the device IMEI or related data, the application will also need to request the +<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> + +<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring +device-specific information for use in your {@code Obfuscator}, consider +how doing so might affect your application or its filtering on Google Play +(since some permissions can cause the SDK build tools to add +the associated <code><uses-feature></code>).</p> + +<p>Finally, construct an instance of AESObfuscator, passing the salt, +application identifier, and device identifier. You can construct the instance +directly, while constructing your {@code Policy} and {@code LicenseChecker}. For example:</p> + +<pre> ... + // Construct the LicenseChecker with a Policy. + mChecker = new LicenseChecker( + this, new ServerManagedPolicy(this, + new AESObfuscator(SALT, getPackageName(), deviceId)), + BASE64_PUBLIC_KEY // Your public licensing key. + ); + ... +</pre> + +<p>For a complete example, see MainActivity in the LVL sample application.</p> + + +<h2 id="impl-lc">Checking the License from an Activity</h2> + +<p>Once you've implemented a {@code Policy} for managing access to your application, the +next step is to add a license check to your application, which initiates a query +to the licensing server if needed and manages access to the application based on +the license response. All of the work of adding the license check and handling +the response takes place in your main {@link android.app.Activity} source file. +</p> + +<p>To add the license check and handle the response, you must:</p> + +<ol> + <li><a href="#imports">Add imports</a></li> + <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> + <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> + <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> + <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> + <li><a href="#account-key">Embed your public key</a> for licensing</li> + <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> +</ol> + +<p>The sections below describe these tasks. </p> + +<h3 id="lc-overview">Overview of license check and response</h3> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Example: MainActivity</h2> + +<p>The sample application included with the LVL provides a full example of how +to initiate a license check and handle the result, in the +<code>MainActivity.java</code> file.</p> + +</div> +</div> + +<p>In most cases, you should add the license check to your application's main +{@link android.app.Activity}, in the {@link android.app.Activity#onCreate onCreate()} method. This +ensures that when the user launches your application directly, the license check +will be invoked immediately. In some cases, you can add license checks in other +locations as well. For example, if your application includes multiple Activity +components that other applications can start by {@link android.content.Intent}, +you could add license checks in those Activities.</p> + +<p>A license check consists of two main actions: </p> + +<ul> +<li>A call to a method to initiate the license check — in the LVL, this is +a call to the <code>checkAccess()</code> method of a {@code LicenseChecker} object that +you construct.</li> +<li>A callback that returns the result of the license check. In the LVL, this is +a <code>LicenseCheckerCallback</code> interface that you implement. The +interface declares two methods, <code>allow()</code> and +<code>dontAllow()</code>, which are invoked by the library based on to the +result of the license check. You implement these two methods with whatever logic +you need, to allow or disallow the user access to your application. Note that +these methods do not determine <em>whether</em> to allow access — that +determination is the responsibility of your {@code Policy} implementation. Rather, these +methods simply provide the application behaviors for <em>how</em> to allow and +disallow access (and handle application errors). + <p>The <code>allow()</code> and <code>dontAllow()</code> methods do provide a "reason" +for their response, which can be one of the {@code Policy} values, {@code LICENSED}, +{@code NOT_LICENSED}, or {@code RETRY}. In particular, you should handle the case in which +the method receives the {@code RETRY} response for {@code dontAllow()} and provide the user with an +"Retry" button, which might have happened because the service was unavailable during the +request.</p></li> +</ul> + +<div style="margin-bottom:2em;"> + +<img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> +<div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a +typical license check interaction.</div> +</div> + +<p>The diagram above illustrates how a typical license check takes place: </p> + +<ol> +<li>Code in the application's main Activity instantiates {@code LicenseCheckerCallback} +and {@code LicenseChecker} objects. When constructing {@code LicenseChecker}, the code passes in +{@link android.content.Context}, a {@code Policy} implementation to use, and the +publisher account's public key for licensing as parameters. </li> +<li>The code then calls the <code>checkAccess()</code> method on the +{@code LicenseChecker} object. The method implementation calls the {@code Policy} to determine +whether there is a valid license response cached locally, in +{@link android.content.SharedPreferences}. + <ul> + <li>If so, the <code>checkAccess()</code> implementation calls + <code>allow()</code>.</li> + <li>Otherwise, the {@code LicenseChecker} initiates a license check request that is sent + to the licensing server.</li> + </ul> + +<p class="note"><strong>Note:</strong> The licensing server always returns +<code>LICENSED</code> when you perform a license check of a draft application.</p> +</li> +<li>When a response is received, {@code LicenseChecker} creates a LicenseValidator that +verifies the signed license data and extracts the fields of the response, then +passes them to your {@code Policy} for further evaluation. + <ul> + <li>If the license is valid, the {@code Policy} caches the response in +{@link android.content.SharedPreferences} and notifies the validator, which then calls the +<code>allow()</code> method on the {@code LicenseCheckerCallback} object. </li> + <li>If the license not valid, the {@code Policy} notifies the validator, which calls +the <code>dontAllow()</code> method on {@code LicenseCheckerCallback}. </li> + </ul> +</li> +<li>In case of a recoverable local or server error, such as when the network is +not available to send the request, {@code LicenseChecker} passes a {@code RETRY} response to +your {@code Policy} object's <code>processServerResponse()</code> method. + <p>Also, both the {@code allow()} and {@code dontAllow()} callback methods receive a +<code>reason</code> argument. The {@code allow()} method's reason is usually {@code +Policy.LICENSED} or {@code Policy.RETRY} and the {@code dontAllow()} reason is usually {@code +Policy.NOT_LICENSED} or {@code Policy.RETRY}. These response values are useful so you can show +an appropriate response for the user, such as by providing a "Retry" button when {@code +dontAllow()} responds with {@code Policy.RETRY}, which might have been because the service was +unavailable.</p></li> +<li>In case of a application error, such as when the application attempts to +check the license of an invalid package name, {@code LicenseChecker} passes an error +response to the LicenseCheckerCallback's <code>applicationError()</code> +method. </li> +</ol> + +<p>Note that, in addition to initiating the license check and handling the +result, which are described in the sections below, your application also needs +to provide a <a href="#impl-Policy">Policy implementation</a> and, if the {@code Policy} +stores response data (such as ServerManagedPolicy), an <a +href="#impl-Obfuscator">Obfuscator</a> implementation. </p> + + +<h3 id="imports">Add imports</h3> + +<p>First, open the class file of the application's main Activity and import +{@code LicenseChecker} and {@code LicenseCheckerCallback} from the LVL package.</p> + +<pre> import com.android.vending.licensing.LicenseChecker; + import com.android.vending.licensing.LicenseCheckerCallback;</pre> + +<p>If you are using the default {@code Policy} implementation provided with the LVL, +ServerManagedPolicy, import it also, together with the AESObfuscator. If you are +using a custom {@code Policy} or {@code Obfuscator}, import those instead. </p> + +<pre> import com.android.vending.licensing.ServerManagedPolicy; + import com.android.vending.licensing.AESObfuscator;</pre> + +<h3 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h3> + +<p>{@code LicenseCheckerCallback} is an interface provided by the LVL for handling +result of a license check. To support licensing using the LVL, you must +implement {@code LicenseCheckerCallback} and +its methods to allow or disallow access to the application.</p> + +<p>The result of a license check is always a call to one of the +{@code LicenseCheckerCallback} methods, made based on the validation of the response +payload, the server response code itself, and any additional processing provided +by your {@code Policy}. Your application can implement the methods in any way needed. In +general, it's best to keep the methods simple, limiting them to managing UI +state and application access. If you want to add further processing of license +responses, such as by contacting a backend server or applying custom constraints, +you should consider incorporating that code into your {@code Policy}, rather than +putting it in the {@code LicenseCheckerCallback} methods. </p> + +<p>In most cases, you should declare your implementation of +{@code LicenseCheckerCallback} as a private class inside your application's main +Activity class. </p> + +<p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as +needed. To start with, you can use simple result-handling behaviors in the +methods, such as displaying the license result in a dialog. This helps you get +your application running sooner and can assist with debugging. Later, after you +have determined the exact behaviors you want, you can add more complex handling. +</p> + +<p>Some suggestions for handling unlicensed responses in +<code>dontAllow()</code> include: </p> + +<ul> +<li>Display a "Try again" dialog to the user, including a button to initiate a +new license check if the <code>reason</code> supplied is {@code Policy.RETRY}. </li> +<li>Display a "Purchase this application" dialog, including a button that +deep-links the user to the application's details page on Google Play, from which the +use can purchase the application. For more information on how to set up such +links, see <a +href="{@docRoot}guide/publishing/publishing.html#marketintent">Linking to your apps +on Google Play</a>. </li> +<li>Display a Toast notification that indicates that the features of the +application are limited because it is not licensed. </li> +</ul> + +<p>The example below shows how the LVL sample application implements +{@code LicenseCheckerCallback}, with methods that display the license check result in a +dialog. </p> + +<pre> +private class MyLicenseCheckerCallback implements LicenseCheckerCallback { + public void allow(int reason) { + if (isFinishing()) { + // Don't update UI if Activity is finishing. + return; + } + // Should allow user access. + displayResult(getString(R.string.allow)); + } + + public void dontAllow(int reason) { + if (isFinishing()) { + // Don't update UI if Activity is finishing. + return; + } + displayResult(getString(R.string.dont_allow)); + + if (reason == Policy.RETRY) { + // If the reason received from the policy is RETRY, it was probably + // due to a loss of connection with the service, so we should give the + // user a chance to retry. So show a dialog to retry. + showDialog(DIALOG_RETRY); + } else { + // Otherwise, the user is not licensed to use this app. + // Your response should always inform the user that the application + // is not licensed, but your behavior at that point can vary. You might + // provide the user a limited access version of your app or you can + // take them to Google Play to purchase the app. + showDialog(DIALOG_GOTOMARKET); + } + } +} +</pre> + +<p>Additionally, you should implement the <code>applicationError()</code> +method, which the LVL calls to let your application handle errors that are not +retryable. For a list of such errors, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> in the <a +href="guide/market/licensing/licensing-reference.html">Licensing Reference</a>. You can implement +the method in any way needed. In most cases, the +method should log the error code and call <code>dontAllow()</code>.</p> + +<h3 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback +to the UI thread</h3> + +<p>During a license check, the LVL passes the request to the Google Play +application, which handles communication with the licensing server. The LVL +passes the request over asynchronous IPC (using {@link android.os.Binder}) so +the actual processing and network communication do not take place on a thread +managed by your application. Similarly, when the Google Play application +receives the result, it invokes a callback method over IPC, which in turn +executes in an IPC thread pool in your application's process.</p> + +<p>The {@code LicenseChecker} class manages your application's IPC communication with +the Google Play application, including the call that sends the request and +the callback that receives the response. {@code LicenseChecker} also tracks open license +requests and manages their timeouts. </p> + +<p>So that it can handle timeouts properly and also process incoming responses +without affecting your application's UI thread, {@code LicenseChecker} spawns a +background thread at instantiation. In the thread it does all processing of +license check results, whether the result is a response received from the server +or a timeout error. At the conclusion of processing, the LVL calls your +{@code LicenseCheckerCallback} methods from the background thread. </p> + +<p>To your application, this means that:</p> + +<ol> +<li>Your {@code LicenseCheckerCallback} methods will be invoked, in many cases, from a +background thread.</li> +<li>Those methods won't be able to update state or invoke any processing in the +UI thread, unless you create a Handler in the UI thread and have your callback +methods post to the Handler.</li> +</ol> + +<p>If you want your {@code LicenseCheckerCallback} methods to update the UI thread, +instantiate a {@link android.os.Handler} in the main Activity's +{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, +as shown below. In this example, the LVL sample application's +{@code LicenseCheckerCallback} methods (see above) call <code>displayResult()</code> to +update the UI thread through the Handler's +{@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> + +<pre>private Handler mHandler; + + @Override + public void onCreate(Bundle savedInstanceState) { + ... + mHandler = new Handler(); + } +</pre> + +<p>Then, in your {@code LicenseCheckerCallback} methods, you can use Handler methods to +post Runnable or Message objects to the Handler. Here's how the sample +application included in the LVL posts a Runnable to a Handler in the UI thread +to display the license status.</p> + +<pre> private void displayResult(final String result) { + mHandler.post(new Runnable() { + public void run() { + mStatusText.setText(result); + setProgressBarIndeterminateVisibility(false); + mCheckLicenseButton.setEnabled(true); + } + }); + } +</pre> + +<h3 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h3> + +<p>In the main Activity's +{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, +create private instances of LicenseCheckerCallback and {@code LicenseChecker}. You must +instantiate {@code LicenseCheckerCallback} first, because you need to pass a reference +to that instance when you call the constructor for {@code LicenseChecker}. </p> + +<p>When you instantiate {@code LicenseChecker}, you need to pass in these parameters:</p> + +<ul> +<li>The application {@link android.content.Context}</li> +<li>A reference to the {@code Policy} implementation to use for the license check. In +most cases, you would use the default {@code Policy} implementation provided by the LVL, +ServerManagedPolicy. </li> +<li>The String variable holding your publisher account's public key for +licensing. </li> +</ul> + +<p>If you are using ServerManagedPolicy, you won't need to access the class +directly, so you can instantiate it in the {@code LicenseChecker} constructor, +as shown in the example below. Note that you need to pass a reference to a new +Obfuscator instance when you construct ServerManagedPolicy.</p> + +<p>The example below shows the instantiation of {@code LicenseChecker} and +{@code LicenseCheckerCallback} from the <code>onCreate()</code> method of an Activity +class. </p> + +<pre>public class MainActivity extends Activity { + ... + private LicenseCheckerCallback mLicenseCheckerCallback; + private LicenseChecker mChecker; + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + ... + // Construct the LicenseCheckerCallback. The library calls this when done. + mLicenseCheckerCallback = new MyLicenseCheckerCallback(); + + // Construct the LicenseChecker with a Policy. + mChecker = new LicenseChecker( + this, new ServerManagedPolicy(this, + new AESObfuscator(SALT, getPackageName(), deviceId)), + BASE64_PUBLIC_KEY // Your public licensing key. + ); + ... + } +} +</pre> + + +<p>Note that {@code LicenseChecker} calls the {@code LicenseCheckerCallback} methods from the UI +thread <em>only</em> if there is valid license response cached locally. If the +license check is sent to the server, the callbacks always originate from the +background thread, even for network errors. </p> + + +<h3 id="check-access">Call checkAccess() to initiate the license check</h3> + +<p>In your main Activity, add a call to the <code>checkAccess()</code> method of the +{@code LicenseChecker} instance. In the call, pass a reference to your +{@code LicenseCheckerCallback} instance as a parameter. If you need to handle any +special UI effects or state management before the call, you might find it useful +to call <code>checkAccess()</code> from a wrapper method. For example, the LVL +sample application calls <code>checkAccess()</code> from a +<code>doCheck()</code> wrapper method:</p> + +<pre> @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + ... + // Call a wrapper method that initiates the license check + doCheck(); + ... + } + ... + private void doCheck() { + mCheckLicenseButton.setEnabled(false); + setProgressBarIndeterminateVisibility(true); + mStatusText.setText(R.string.checking_license); + mChecker.checkAccess(mLicenseCheckerCallback); + } +</pre> + + +<h3 id="account-key">Embed your public key for licensing</h3> + +<p>For each publisher account, the Google Play service automatically +generates a 2048-bit RSA public/private key pair that is used exclusively for +licensing. The key pair is uniquely associated with the publisher account and is +shared across all applications that are published through the account. Although +associated with a publisher account, the key pair is <em>not</em> the same as +the key that you use to sign your applications (or derived from it).</p> + +<p>The Google Play publisher site exposes the public key for licensing to any +developer signed in to the publisher account, but it keeps the private key +hidden from all users in a secure location. When an application requests a +license check for an application published in your account, the licensing server +signs the license response using the private key of your account's key pair. +When the LVL receives the response, it uses the public key provided by the +application to verify the signature of the license response. </p> + +<p>To add licensing to an application, you must obtain your publisher account's +public key for licensing and copy it into your application. Here's how to find +your account's public key for licensing:</p> + +<ol> +<li>Go to the Google Play <a +href="http://play.google.com/apps/publish">publisher site</a> and sign in. +Make sure that you sign in to the account from which the application you are +licensing is published (or will be published). </li> +<li>In the account home page, locate the "Edit profile" link and click it. </li> +<li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your +public key for licensing is given in the "Public key" text box. </li> +</ol> + +<p>To add the public key to your application, simply copy/paste the key string +from the text box into your application as the value of the String variable +<code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have +selected the entire key string, without omitting any characters. </p> + +<p>Here's an example from the LVL sample application:</p> + +<pre> public class MainActivity extends Activity { + private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example + ... + } +</pre> + +<h3 id="handler-cleanup">Call your LicenseChecker's onDestroy() method +to close IPC connections</h3> + +<p>Finally, to let the LVL clean up before your application +{@link android.content.Context} changes, add a call to the {@code LicenseChecker}'s +<code>onDestroy()</code> method from your Activity's +{@link android.app.Activity#onDestroy()} implementation. The call causes the +{@code LicenseChecker} to properly close any open IPC connection to the Google Play +application's ILicensingService and removes any local references to the service +and handler.</p> + +<p>Failing to call the {@code LicenseChecker}'s <code>onDestroy()</code> method +can lead to problems over the lifecycle of your application. For example, if the +user changes screen orientation while a license check is active, the application +{@link android.content.Context} is destroyed. If your application does not +properly close the {@code LicenseChecker}'s IPC connection, your application will crash +when the response is received. Similarly, if the user exits your application +while a license check is in progress, your application will crash when the +response is received, unless it has properly called the +{@code LicenseChecker}'s <code>onDestroy()</code> method to disconnect from the service. +</p> + +<p>Here's an example from the sample application included in the LVL, where +<code>mChecker</code> is the {@code LicenseChecker} instance:</p> + +<pre> @Override + protected void onDestroy() { + super.onDestroy(); + mChecker.onDestroy(); + ... + } +</pre> + +<p>If you are extending or modifying {@code LicenseChecker}, you might also need to call +the {@code LicenseChecker}'s <code>finishCheck()</code> method, to clean up any open IPC +connections.</p> + +<h2 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h2> + +<p>In some cases, you might want your {@code Policy} to limit the number of actual +devices that are permitted to use a single license. This would prevent a user +from moving a licensed application onto a number of devices and using the +application on those devices under the same account ID. It would also prevent a +user from "sharing" the application by providing the account information +associated with the license to other individuals, who could then sign in to that +account on their devices and access the license to the application. </p> + +<p>The LVL supports per-device licensing by providing a +<code>DeviceLimiter</code> interface, which declares a single method, +<code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response +from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a +user ID string extracted from the response.</p> + +<p>If you do not want to support device limitation, <strong>no work is +required</strong> — the {@code LicenseChecker} class automatically uses a default +implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter +is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns +a <code>LICENSED</code> response for all users and devices. </p> + +<div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> +<p><strong>Caution:</strong> Per-device licensing is <em>not recommended for +most applications</em> because:</p> +<ul> +<li>It requires that you provide a backend server to manage a users and devices +mapping, and </li> +<li>It could inadvertently result in a user being denied access to an +application that they have legitimately purchased on another device.</li> +</ul> +</div> + + + + + + + + + + + +<h2 id="app-obfuscation">Obfuscating Your Code</h2> + +<p>To ensure the security of your application, particularly for a paid +application that uses licensing and/or custom constraints and protections, it's +very important to obfuscate your application code. Properly obfuscating your +code makes it more difficult for a malicious user to decompile the application's +bytecode, modify it — such as by removing the license check — +and then recompile it.</p> + +<p>Several obfuscator programs are available for Android applications, including +<a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers +code-optimization features. The use of ProGuard or a similar program to obfuscate +your code is <em>strongly recommended</em> for all applications that use Google +Play Licensing. </p> + +<h2 id="app-publishing">Publishing a Licensed Application</h2> + +<p>When you are finished testing your license implementation, you are ready to +publish the application on Google Play. Follow the normal steps to <a +href="{@docRoot}guide/publishing/preparing.html">prepare</a>, <a +href="{@docRoot}guide/publishing/app-signing.html">sign</a>, and then <a +href="{@docRoot}guide/publishing/publishing.html">publish the application</a>. +</p> + +<h3>Removing Copy Protection</h3> + +<p>After uploading your licensed application, remember to remove copy protection +from the application, if it is currently used. To check and remove copy +protection, sign in to the publisher site and go the application's upload +details page. In the Publishing options section, make sure that the Copy +Protection radio button selection is "Off".</p> + + +<h2 id="support">Where to Get Support</h2> + +<p>If you have questions or encounter problems while implementing or deploying +publishing in your applications, please use the support resources listed in the +table below. By directing your queries to the correct forum, you can get the +support you need more quickly. </p> + +<p class="table-caption"><strong>Table 2.</strong> Developer support resources +for Google Play Licensing Service.</p> + +<table> + +<tr> +<th>Support Type</th> +<th>Resource</th> +<th>Range of Topics</th> +</tr> +<tr> +<td rowspan="2">Development and testing issues</td> +<td>Google Groups: <a +href="http://groups.google.com/group/android-developers">android-developers</a> +</td> +<td rowspan="2">LVL download and integration, library projects, {@code Policy} +questions, user experience ideas, handling of responses, {@code Obfuscator}, IPC, test +environment setup</td> +</tr> +<tr> +<td>Stack Overflow: <a +href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> +</tr> +<tr> +<td rowspan="2">Accounts, publishing, and deployment issues</td> +<td><a href="http://www.google.com/support/forum/p/Android+Market">Google Play +Help Forum</a></td> +<td rowspan="2">Publisher accounts, licensing key pair, test accounts, server +responses, test responses, application deployment and results</td> +</tr> +<tr> +<td><a +href="http://market.android.com/support/bin/answer.py?answer=186113">Market +Licensing Support FAQ</a></td> +</tr> +<tr> +<td>LVL issue tracker</td> +<td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing +project issue tracker</a></td> +<td>Bug and issue reports related specifically to the LVL source code classes +and interface implementations</td> +</tr> + +</table> + +<p>For general information about how to post to the groups listed above, see <a +href="{@docRoot}resources/community-groups.html">Developer Forums</a> document +in the Resources tab.</p> + + diff --git a/docs/html/guide/market/licensing/index.jd b/docs/html/guide/market/licensing/index.jd new file mode 100644 index 0000000..1f15303 --- /dev/null +++ b/docs/html/guide/market/licensing/index.jd @@ -0,0 +1,61 @@ +page.title=Application Licensing +@jd:body + + +<p>Google Play offers a licensing service that lets you enforce licensing policies for +applications that you publish on Google Play. With Google Play Licensing, your application can +query Google Play at run time to obtain the licensing status for the current user, then allow or +disallow further use as appropriate. </p> + +<p>Using the service, you can apply a flexible licensing policy on an application-by-application +basis—each application can enforce licensing in the way most appropriate for it. If necessary, +an application can apply custom constraints based on the licensing status obtained from Google Play. +For example, an application can check the licensing status and then apply custom constraints +that allow the user to run it unlicensed for a specific validity period. An application can also +restrict use of the application to a specific device, in addition to any other constraints. </p> + +<p>The licensing service is a secure means of controlling access to your applications. When an +application checks the licensing status, the Google Play server signs the licensing status +response using a key pair that is uniquely associated with the publisher account. Your application +stores the public key in its compiled <code>.apk</code> file and uses it to verify the licensing +status response.</p> + +<p>Any application that you publish through Google Play can use the Google Play Licensing +service. No special account or registration is needed. Additionally, because the service uses no +dedicated framework APIs, you can add licensing to any application that uses a minimum API level of +3 or higher.</p> + +<p class="note"><strong>Note:</strong> The Google Play Licensing service is primarily intended +for paid applications that wish to verify that the current user did in fact pay for the application +on Google Play. However, any application (including free apps) may use the licensing service +to initiate the download of an APK expansion file. In which case, the request that your application +sends to the licensing service is not to check whether the user paid for the app, but to request the +URL of the expansion files. For information about downloading expansion files for your application, +read the guide to <a href="{@docRoot}guide/market/expansion-files.html">APK Expansion Files</a>.</p> + + +<p>To learn more about Google Play's application licensing service and start integrating it into +your applications, read the following documents:</p> + +<dl> + <dt><strong><a href="{@docRoot}guide/market/licensing/overview.html">Licensing +Overview</a></strong></dt> + <dd>Describes how the service works and what a typical licensing implementation looks +like.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for +Licensing</a></strong></dt> + <dd>Explains how to set up your Google Play account, development environment, and +testing environment in order to add licensing to your app.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a></strong></dt> + <dd>Provides a step-by-step guide to add licensing verification to your application.</dd> + <dt><strong><a href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing +Reference</a></strong></dt> + <dd>Provides detailed information about the licensing library's classes and the service response +codes.</dd> +</dl> + + + + + diff --git a/docs/html/guide/market/licensing/licensing-reference.jd b/docs/html/guide/market/licensing/licensing-reference.jd new file mode 100644 index 0000000..0a7e033 --- /dev/null +++ b/docs/html/guide/market/licensing/licensing-reference.jd @@ -0,0 +1,439 @@ +page.title=Licensing Reference +parent.title=Application Licensing +parent.link=index.html +@jd:body + + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#lvl-summary">LVL Classes and Interfaces</a></li> + <li><a href="#server-response-codes">Server Response Codes</a></li> + <li><a href="#extras">Server Response Extras</a></li> + </ol> + +</div> +</div> + + +<h2 id="lvl-summary">LVL Classes and Interfaces</h2> + +<p>Table 1 lists all of the source files in the License Verification +Library (LVL) available through the Android SDK. All of the files are part of +the <code>com.android.vending.licensing</code> package.</p> + +<p class="table-caption"><strong>Table 1.</strong> Summary of LVL library +classes and interfaces.</p> + +<div style="width:99%"> +<table width="100%"> + +<tr> +<th width="15%">Category</th> +<th width="20%">Name</th> +<th width="100%">Description</th> +</tr> + +<tr> +<td rowspan="2">License check and result</td> +<td>LicenseChecker</td> +<td>Class that you instantiate (or subclass) to initiate a license check.</td> +</tr> +<tr> +<td><em>LicenseCheckerCallback</em></td> +<td>Interface that you implement to handle result of the license check.</td> +</tr> + +<tr> +<td rowspan="3" width="15%">Policy</td> +<td width="20%"><em>Policy</em></td> +<td width="100%">Interface that you implement to determine whether to allow +access to the application, based on the license response. </td> +</tr> +<tr> +<td>ServerManagedPolicy</td> +<td width="100%">Default {@code Policy} implementation. Uses settings provided by the +licensing server to manage local storage of license data, license validity, +retry.</td> +</tr> +<tr> +<td>StrictPolicy</td> +<td>Alternative {@code Policy} implementation. Enforces licensing based on a direct +license response from the server only. No caching or request retry.</td> +</tr> + +<tr> +<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td> +<td width="20%"><em>Obfuscator</em></td> +<td width="100%">Interface that you implement if you are using a {@code Policy} (such as +ServerManagedPolicy) that caches license response data in a persistent store. +Applies an obfuscation algorithm to encode and decode data being written or +read.</td> +</tr> +<tr> +<td>AESObfuscator</td> +<td>Default Obfuscator implementation that uses AES encryption/decryption +algorithm to obfuscate/unobfuscate data.</td> +</tr> + +<tr> +<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td> +<td width="20%"><em>DeviceLimiter</em></td> +<td width="100%">Interface that you implement if you want to restrict use of an +application to a specific device. Called from LicenseValidator. Implementing +DeviceLimiter is not recommended for most applications because it requires a +backend server and may cause the user to lose access to licensed applications, +unless designed with care.</td> +</tr> +<tr> +<td>NullDeviceLimiter</td> +<td>Default DeviceLimiter implementation that is a no-op (allows access to all +devices).</td> +</tr> + +<tr> +<td rowspan="6" width="15%">Library core, no integration needed</td> +<td width="20%">ResponseData</td> +<td width="100%">Class that holds the fields of a license response.</td> +</tr> +<tr> +<td>LicenseValidator</td> +<td>Class that decrypts and verifies a response received from the licensing +server.</td> +</tr> +<tr> +<td>ValidationException</td> +<td>Class that indicates errors that occur when validating the integrity of data +managed by an Obfuscator.</td> +</tr> +<tr> +<td>PreferenceObfuscator</td> +<td>Utility class that writes/reads obfuscated data to the system's +{@link android.content.SharedPreferences} store.</td> +</tr> +<tr> +<td><em>ILicensingService</em></td> +<td>One-way IPC interface over which a license check request is passed to the +Google Play client.</td> +</tr> +<tr> +<td><em>ILicenseResultListener</em></td> +<td>One-way IPC callback implementation over which the application receives an +asynchronous response from the licensing server.</td> +</tr> + +</table> +</div> + + +<h2 id="server-response-codes">Server Response Codes</h2> + +<p>Table 2 lists all of the license response codes supported by the +licensing server. In general, an application should handle all of these response +codes. By default, the LicenseValidator class in the LVL provides all of the +necessary handling of these response codes for you. </p> + +<p class="table-caption"><strong>Table 2.</strong> Summary of response codes +returned by the Google Play server in a license response.</p> + +<table> + +<tr> +<th>Response Code</th> +<th>Description</th> +<th>Signed?</th> +<th>Extras</th> +<th>Comments</th> +</tr> +<tr> +<td>{@code LICENSED}</td> +<td>The application is licensed to the user. The user has purchased the +application or the application only exists as a draft.</td> +<td>Yes</td> +<td><code>VT</code>, <code>GT</code>, <code>GR</code></td> +<td><em>Allow access according to {@code Policy} constraints.</em></td> +</tr> +<tr> +<td>{@code LICENSED_OLD_KEY}</td> +<td>The application is licensed to the user, but there is an updated application +version available that is signed with a different key. </td> +<td>Yes </td> +<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td> +<td><em>Optionally allow access according to {@code Policy} constraints.</em> +<p style="margin-top:.5em;">Can indicate that the key pair used by the installed +application version is invalid or compromised. The application can allow access +if needed or inform the user that an upgrade is available and limit further use +until upgrade.</p> +</td> +</tr> +<tr> +<td>{@code NOT_LICENSED}</td> +<td>The application is not licensed to the user.</td> +<td>No</td> +<td></td> +<td><em>Do not allow access.</em></td> +</tr> +<tr> +<td>{@code ERROR_CONTACTING_SERVER}</td> +<td>Local error — the Google Play application was not able to reach the +licensing server, possibly because of network availability problems. </td> +<td>No</td> +<td></td> +<td><em>Retry the license check according to {@code Policy} retry limits.</em></td> +</tr> +<tr> +<td>{@code ERROR_SERVER_FAILURE}</td> +<td>Server error — the server could not load the publisher account's key +pair for licensing.</td> +<td>No</td> +<td></td> +<td><em>Retry the license check according to {@code Policy} retry limits.</em> +</td> +</tr> +<tr> +<td>{@code ERROR_INVALID_PACKAGE_NAME}</td> +<td>Local error — the application requested a license check for a package +that is not installed on the device. </td> +<td>No </td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Typically caused by a development error.</p> +</td> +</tr> +<tr> +<td>{@code ERROR_NON_MATCHING_UID}</td> +<td>Local error — the application requested a license check for a package +whose UID (package, user ID pair) does not match that of the requesting +application. </td> +<td>No </td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Typically caused by a development error.</p> +</td> +</tr> +<tr> +<td>{@code ERROR_NOT_MARKET_MANAGED}</td> +<td>Server error — the application (package name) was not recognized by +Google Play. </td> +<td>No</td> +<td></td> +<td><em>Do not retry the license check.</em> +<p style="margin-top:.5em;">Can indicate that the application was not published +through Google Play or that there is an development error in the licensing +implementation.</p> +</td> +</tr> + +</table> + +<p class="note"><strong>Note:</strong> As documented in <a +href="{@docRoot}guide/market/licensing/setting-up.html#test-env"> +Setting Up The Testing Environment</a>, the response code can be manually +overridden for the application developer and any registered test users via the +Google Play publisher site. +<br/><br/> +Additionally, as noted above, applications that are in draft mode (in other +words, applications that have been uploaded but have <em>never</em> been +published) will return {@code LICENSED} for all users, even if not listed as a test +user. Since the application has never been offered for download, it is assumed +that any users running it must have obtained it from an authorized channel for +testing purposes.</p> + + + + +<h2 id="extras">Server Response Extras</h2> + +<p>To assist your application in managing access to the application across the application refund +period and provide other information, The licensing server includes several pieces of +information in the license responses. Specifically, the service provides recommended values for the +application's license validity period, retry grace period, maximum allowable retry count, and other +settings. If your application uses <a href="{@docRoot}guide/market/expansion-files.html">APK +expansion files</a>, the response also includes the file names, sizes, and URLs. The server appends +the settings as key-value pairs in the license response "extras" field. </p> + +<p>Any {@code Policy} implementation can extract the extras settings from the license +response and use them as needed. The LVL default {@code Policy} implementation, <a +href="{@docRoot}guide/market/licensing/adding-licensing.html#ServerManagedPolicy">{@code +ServerManagedPolicy}</a>, serves as a working +implementation and an illustration of how to obtain, store, and use the +settings. </p> + +<p class="table-caption"><strong>Table 3.</strong> Summary of +license-management settings supplied by the Google Play server in a license +response.</p> + +<table> +<tr> +<th>Extra</th><th>Description</th> +</tr> + +<tr> + <td>{@code VT}</td> + <td>License validity timestamp. Specifies the date/time at which the current +(cached) license response expires and must be rechecked on the licensing server. See the section +below about <a href="#VT">License validity period</a>. + </td> +</tr> +<tr> + <td>{@code GT}</td> + <td>Grace period timestamp. Specifies the end of the period during which a +Policy may allow access to the application, even though the response status is +{@code RETRY}. <p>The value is managed by the server, however a typical value would be 5 +or more days. See the section +below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td> +</tr> +<tr> + <td>{@code GR}</td> + <td>Maximum retries count. Specifies how many consecutive {@code RETRY} license checks +the {@code Policy} should allow, before denying the user access to the application. +<p>The value is managed by the server, however a typical value would be "10" or +higher. See the section +below about <a href="#GTGR">Retry period and maximum retry count</a>.</p></td> +</tr> +<tr> + <td>{@code UT}</td> + <td>Update timestamp. Specifies the day/time when the most recent update to +this application was uploaded and published. <p>The server returns this extra +only for {@code LICENSED_OLD_KEYS} responses, to allow the {@code Policy} to determine how much +time has elapsed since an update was published with new licensing keys before +denying the user access to the application. </p></td> +</tr> + + +<!-- APK EXPANSION FILE RESPONSES --> + +<tr> + <td>{@code FILE_URL1} or {@code FILE_URL2}</td> + <td>The URL for an expansion file (1 is for the main file, 2 is the patch file). Use this to +download the file over HTTP.</td> +</tr> +<tr> + <td>{@code FILE_NAME1} or {@code FILE_NAME2}</td> + <td>The expansion file's name (1 is for the main file, 2 is the patch file). You must use this +name when saving the file on the device.</td> +</tr> +<tr> + <td>{@code FILE_SIZE1} or {@code FILE_SIZE2}</td> + <td>The size of the file in bytes (1 is for the main file, 2 is the patch file). Use this to +assist with downloading and to ensure that enough space is available on the device's shared +storage location before downloading.</td> +</tr> + +</table> + + + +<h4 id="VT">License validity period</h4> + +<p>The Google Play licensing server sets a license validity period for all +downloaded applications. The period expresses the interval of time over which an +application's license status should be considered as unchanging and cacheable by +a licensing {@code Policy} in the application. The licensing server includes the +validity period in its response to all license checks, appending an +end-of-validity timestamp to the response as an extra under the key {@code VT}. A +{@code Policy} can extract the VT key value and use it to conditionally allow access to +the application without rechecking the license, until the validity period +expires. </p> + +<p>The license validity signals to a licensing {@code Policy} when it must recheck the +licensing status with the licensing server. It is <em>not</em> intended to imply +whether an application is actually licensed for use. That is, when an +application's license validity period expires, this does not mean that the +application is no longer licensed for use — rather, it indicates only that +the {@code Policy} must recheck the licensing status with the server. It follows that, +as long as the license validity period has not expired, it is acceptable for the +{@code Policy} to cache the initial license status locally and return the cached license +status instead of sending a new license check to the server.</p> + +<p>The licensing server manages the validity period as a means of helping the +application properly enforce licensing across the refund period offered by +Google Play for paid applications. It sets the validity period based on +whether the application was purchased and, if so, how long ago. Specifically, +the server sets a validity period as follows:</p> + +<ul> +<li>For a paid application, the server sets the initial license validity period +so that the license response remains valid for as long as the application is +refundable. A licensing {@code Policy} in the application may cache the +result of the initial license check and does not need to recheck the license +until the validity period has expired.</li> +<li>When an application is no longer refundable, the server +sets a longer validity period — typically a number of days. </li> + +<!-- TODO: Verify the following behavior is still true w/ OBB: --> +<li>For a free application, the server sets the validity period to a very high +value (<code>long.MAX_VALUE</code>). This ensures that, provided the {@code Policy} has +cached the validity timestamp locally, it will not need to recheck the +license status of the application in the future.</li> +</ul> + +<p>The {@code ServerManagedPolicy} implementation uses the extracted timestamp +(<code>mValidityTimestamp</code>) as a primary condition for determining whether +to recheck the license status with the server before allowing the user access to +the application. </p> + + +<h4 id="GTGR">Retry period and maximum retry count</h4> + +<p>In some cases, system or network conditions can prevent an application's +license check from reaching the licensing server, or prevent the server's +response from reaching the Google Play client application. For example, the +user might launch an application when there is no cell network or data +connection available—such as when on an airplane—or when the +network connection is unstable or the cell signal is weak. </p> + +<p>When network problems prevent or interrupt a license check, the Google +Play client notifies the application by returning a {@code RETRY} response code to +the {@code Policy}'s <code>processServerResponse()</code> method. In the case of system +problems, such as when the application is unable to bind with Google Play's +{@code ILicensingService} implementation, the {@code LicenseChecker} library itself calls the +Policy <code>processServerResonse()</code> method with a {@code RETRY} response code. +</p> + +<p>In general, the {@code RETRY} response code is a signal to the application that an +error has occurred that has prevented a license check from completing. + +<p>The Google Play server helps an application to manage licensing under +error conditions by setting a retry "grace period" and a recommended maximum +retries count. The server includes these values in all license check responses, +appending them as extras under the keys {@code GT} and {@code GR}. </p> + +<p>The application {@code Policy} can extract the {@code GT} and {@code GR} extras and use them to +conditionally allow access to the application, as follows:</p> + +<ul> +<li>For a license check that results in a {@code RETRY} response, the {@code Policy} should +cache the {@code RETRY} response code and increment a count of {@code RETRY} responses.</li> +<li>The {@code Policy} should allow the user to access the application, provided that +either the retry grace period is still active or the maximum retries count has +not been reached.</li> +</ul> + +<p>The {@code ServerManagedPolicy} uses the server-supplied {@code GT} and {@code GR} values as +described above. The example below shows the conditional handling of the retry +responses in the <code>allow()</code> method. The count of {@code RETRY} responses is +maintained in the <code>processServerResponse()</code> method, not shown. </p> + + +<pre> +public boolean allowAccess() { + long ts = System.currentTimeMillis(); + if (mLastResponse == LicenseResponse.LICENSED) { + // Check if the LICENSED response occurred within the validity timeout. + if (ts <= mValidityTimestamp) { + // Cached LICENSED response is still valid. + return true; + } + } else if (mLastResponse == LicenseResponse.RETRY && + ts < mLastResponseTime + MILLIS_PER_MINUTE) { + // Only allow access if we are within the retry period or we haven't used up our + // max retries. + return (ts <= mRetryUntil || mRetryCount <= mMaxRetries); + } + return false; +}</pre> + diff --git a/docs/html/guide/market/licensing/overview.jd b/docs/html/guide/market/licensing/overview.jd new file mode 100644 index 0000000..e7e23f8 --- /dev/null +++ b/docs/html/guide/market/licensing/overview.jd @@ -0,0 +1,246 @@ +page.title=Licensing Overview +parent.title=Application Licensing +parent.link=index.html +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>Licensing allows you to verify your app was purchased from Google Play</li> + <li>Your app maintains control of how it enforces its licensing status</li> + <li>The service is free for all developers who publish on Google Play</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Secure">License Responses are Secure</a></li> + <li><a href="#LVL">Licensing Verification Library</a></li> + <li><a href="#Reqs">Requirements and Limitations</a></li> + <li><a href="#CopyProtection">Replacement for Copy Protection</a></li> +</ol> + +</div> +</div> + + +<p>Google Play Licensing is a network-based service that lets an application query a trusted +Google Play licensing server to determine whether the application is licensed to the current +device user. The licensing service is based on the capability of the Google Play licensing server +to determine whether a given user is licensed to use a given application. Google Play considers a +user to be licensed if the user is a recorded purchaser of the application.</p> + +<p>The request starts when your application makes a request to a service hosted by +the Google Play client application. The Google Play application then sends a request to +the licensing server and receives the result. The Google Play application sends +the result to your application, which can allow or disallow further use of the +application as needed.</p> + +<p class="note"><strong>Note:</strong> If a paid application has been uploaded to Google Play but +saved only as a draft application (the app is unpublished), the licensing server considers all users +to be licensed users of the application (because it's not even possible to purchase the app). +This exception is necessary in order for you to perform testing of your licensing +implementation.</p> + + +<div class="figure" style="width:469px"> +<img src="{@docRoot}images/licensing_arch.png" alt=""/> +<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a +license check through the License Verification Library and the Google Play +client, which handles communication with the Google Play server.</p> +</div> + + +<p>To properly identify the user and determine the license status, the licensing server requires +information about the application and user—your application and the Google Play client work +together to assemble the information and the Google Play client passes it to the server. </p> + +<p>To help you add licensing to your application, the Android SDK provides a downloadable set of +library sources that you can include in your application project: the Google Market +Licensing package. The License Verification Library (LVL) is a library you can add to your +application that +handles all of the licensing-related communication with the Google Play licensing service. With +the LVL added to your application, your application can determine its licensing status for the +current user by simply calling a method and implementing a callback that receives the status +response.</p> + +<p>Your application does not query the licensing server +directly, but instead calls the Google Play client over remote IPC to +initiate a license request. In the license request:</p> + +<ul> +<li>Your application provides: its package name, a nonce that is later used to +validate any response from the server, and a callback over which the +response can be returned asynchronously.</li> +<li>The Google Play client collects the necessary information about the user and the device, +such as the device's primary Google account username, IMSI, and other +information. It then sends the license check request to the server on behalf of +your application.</li> +<li>The Google Play server evaluates the request using all available information, attempting +to establish the user's identity to a sufficient level of confidence. The server +then checks the user identity against purchase records for your application and +returns a license response, which the Google Play client returns to your +application over the IPC callback.</li> +</ul> + +<p>You can choose when, and how often, you want your application to check its +license and you have full control over how it handles the response, verifies the +signed response data, and enforces access controls.</p> + +<p>Notice that during a license check, your application does not manage any +network connections or use any licensing related APIs in the Android platform.</p> + + + + +<h2 id="Secure">License Responses are Secure</h2> + +<p>To ensure the integrity of each license query, the server signs the license +response data using an RSA key pair that is shared exclusively between the Google Play +server and you.</p> + +<p>The licensing service generates a single licensing key pair for each +publisher account and exposes the public key in your account's profile page. You must copy the +public key from the web site and embed it in your application source code. The server retains the +private key internally and uses it to sign license responses for the applications you +publish with that account.</p> + +<p>When your application receives a signed response, it uses the embedded public +key to verify the data. The use of public key cryptography in the licensing +service makes it possible for the application to detect responses that have been +tampered with or that are spoofed.</p> + + + + +<h2 id="LVL">Licensing Verification Library</h2> + +<p>The Android SDK provides a downloadable package called the Google Market Licensing package, +which includes the License Verification Library (LVL). The LVL greatly simplifies the process of +adding licensing to your application and helps ensure a more secure, robust implementation for your +application. The LVL provides internal classes that handle most of the standard operations of a +license query, such as contacting the Google Play client to initiate a license request and +verifying and validating the responses. It also exposes interfaces that let you easily plug in your +custom code for defining licensing policy and managing access as needed by your application. The key +LVL interfaces are: </p> + +<dl> +<dt>{@code Policy}</dt> + <dd>Your implementation determines whether to allow access to the +application, based on the license response received from the server and any +other data available (such as from a backend server associated with your +application). The implementation can evaluate the various fields of the license +response and apply other constraints, if needed. The implementation also lets +you manage the handling of license checks that result in errors, such as network +errors.</dd> + +<dt>{@code LicenseCheckerCallback}</dt> + <dd>Your implementation manages access to the +application, based on the result of the {@code Policy} object's handling of the license +response. Your implementation can manage access in any way needed, including +displaying the license result in the UI or directing the user to purchase the +application (if not currently licensed).</dd> +</dl> + + +<p>To help you get started with a {@code Policy}, the LVL provides two fully complete +{@code Policy} implementations that you can use without modification or adapt to your +needs:</p> + +<dl> +<dt><a href="adding-licensing.html#ServerManagedPolicy">{@code ServerManagedPolicy}</a></dt> + <dd>A flexible {@code Policy} +that uses settings provided by the licensing server to manage response caching +and access to the application while the device is offline (such as when the +user is on an airplane). For most applications, the use of +{@code ServerManagedPolicy} is highly recommended.</dd> + +<dt><a href="adding-licensing.html#StrictPolicy">{@code StrictPolicy}</a></dt> + <dd>A restrictive {@code Policy} that +does not cache any response data and allows the application access <em>only</em> +when the server returns a licensed response.</dd> +</dl> + +<p>The LVL is available as a downloadable package of the Android SDK. The +package includes both the LVL itself and an example application that shows how +the library should be integrated with your application and how your application +should manage response data, UI interaction, and error conditions. </p> + +<p>The LVL sources are provided as an Android <em>library project</em>, which +means that you can maintain a single set of library sources and share them +across multiple applications. A full test environment is also available through +the SDK, so you can develop and test the licensing implementation in your +applications before publishing them, even if you don't have access to a +physical device.</p> + + + + +<h2 id="Reqs">Requirements and Limitations</h2> + +<p>Google Play Licensing is designed to let you apply license controls to +applications that you publish through Google Play. The service is not +designed to let you control access to applications that are not published +through Google Play or that are run on devices that do not offer the Google +Play client. </p> + +<p>Here are some points to keep in mind as you implement licensing in your +application: </p> + +<ul> +<li>An application can use the service only if the Google Play client is +installed on its host device and the device is running Android 1.5 (API level 3) +or higher.</li> +<li>To complete a license check, the licensing server must be accessible over +the network. You can implement license caching behaviors to manage access to your application when +there is no network connectivity. </li> +<li>The security of your application's licensing controls ultimately relies on +the design of your implementation itself. The service provides the building +blocks that let you securely check licensing, but the actual enforcement and +handling of the license are factors are up to you. By following the best +practices in the following documents, you can help ensure that your implementation will be +secure.</li> +<li>Adding licensing to an application does not affect the way the application +functions when run on a device that does not offer Google Play.</li> +<li>You can implement licensing controls for a free app, but only if you're using the service to +provide <a +href="{@docRoot}guide/market/expansion-files.html">APK expansion files</a>.</li> +</ul> + + + +<h2 id="CopyProtection">Replacement for Copy Protection</h2> + +<p>Google Play Licensing is a flexible, secure mechanism for controlling +access to your applications. It effectively replaces the Copy Protection +mechanism offered on Google Play and gives you wider distribution +potential for your applications. </p> + +<ul> +<li>A limitation of the legacy Copy Protection mechanism on Google Play is +that applications using it can be installed only on compatible devices that +provide a secure internal storage environment. For example, a copy-protected +application cannot be downloaded from Google Play to a device that provides root +access, and the application cannot be installed to a device's SD card. </li> +<li>With Google Play licensing, you can move to a license-based model in +which access is not bound to the characteristics of the host device, but to your +publisher account on Google Play and the licensing policy that you define. +Your application can be installed and controlled on any compatible device on +any storage, including SD card.</li> +</ul> + +<p>Although no license mechanism can completely prevent all unauthorized use, +the licensing service lets you control access for most types of normal usage, +across all compatible devices, locked or unlocked, that run Android 1.5 or +higher version of the platform.</p> + +<p>To begin adding application licensing to your application, continue to <a +href="{@docRoot}guide/market/licensing/setting-up.html">Setting Up for Licensing</a>.</p> + + + + + + diff --git a/docs/html/guide/market/licensing/setting-up.jd b/docs/html/guide/market/licensing/setting-up.jd new file mode 100644 index 0000000..0de7819 --- /dev/null +++ b/docs/html/guide/market/licensing/setting-up.jd @@ -0,0 +1,701 @@ +page.title=Setting Up for Licensing +parent.title=Application Licensing +parent.link=index.html +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#account">Setting Up a Publisher Account</a></li> + <li><a href="#dev-setup">Setting Up the Development Environment</a> + <ol> + <li><a href="#runtime-setup">Setting up the runtime environment</a></li> + <li><a href="#download-lvl">Downloading the LVL</a></li> + <li><a href="#lvl-setup">Setting Up the Licensing Verification Library</a></li> + <li><a href="#add-library">Including the LVL library project sources in your +application</a></li> + </ol> + </li> + <li><a href="#test-env">Setting Up the Testing Environment</a> + <ol> + <li><a href="#test-response">Setting test responses for license checks</a></li> + <li><a href="#test-acct-setup">Setting up test accounts</a></li> + <li><a href="#acct-signin">Signing in to an authorized account in the runtime +environment</a></li> + </ol> + </li> +</ol> +</div> +</div> + +<p>Before you start adding license verification to your application, you need to set up your Google +Play publishing account, your development environment, and test accounts required to verify +your implementation.</p> + + +<h2 id="account">Setting Up a Publisher Account</h2> + +<p>If you don't already have a publisher account for Google Play, you need to register for one +using your Google account and agree to the terms of service on the Google Play publisher site:</p> + +<p style="margin-left:2em;"><a +href="http://play.google.com/apps/publish">http://play.google.com/apps/publish</a> +</p> + +<p>For more information, see <a +href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a>.</p> + +<p>If you already have a publisher account on Google Play, use your existing +account to set up licensing.</p> + +<p>Using your publisher account on Google Play, you can:</p> + +<ul> +<li>Obtain a public key for licensing</li> +<li>Debug and test an application's licensing implementation, prior to +publishing the application</li> +<li>Publish the applications to which you have added licensing support</li> +</ul> + +<h4>Administrative settings for licensing</h4> + +<p>You can manage several +administrative controls for Google Play licensing on the publisher site. The controls are available +in the Edit Profile page, in the "Licensing" panel, shown in figure 1. The controls +let you: </p> + +<ul> +<li>Set up multiple "test accounts," identified by email address. The licensing +server allows users signed in to test accounts on a device or emulator to send +license checks and receive static test responses.</li> +<li>Obtain the account's public key for licensing. When you are implementing +licensing in an application, you must copy the public key string into the +application.</li> +<li>Configure static test responses that the server sends, when it receives a +license check for an application uploaded to the publisher account, from a user +signed in to the publisher account or a test account.</li> +</ul> + + +<img src="{@docRoot}images/licensing_public_key.png" alt=""/> +<p class="img-caption"><strong>Figure 1.</strong> The Licensing +panel of your account's Edit Profile page lets you manage administrative +settings for licensing.</p> + +<p>For more information about how to work with test accounts and static test +responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below. + + + +<h2 id="dev-setup">Setting Up the Development Environment</h2> + +<p>Setting up your environment for licensing involves these tasks:</p> + +<ol> +<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li> +<li><a href="#download-lvl">Downloading the LVL</a> into your SDK </li> +<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li> +<li><a href="#add-library">Including the LVL library project in your application</a></li> +</ol> + +<p>The sections below describe these tasks. When you are done with setup, +you can begin <a href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a>.</p> + +<p>To get started, you need to set up a proper runtime environment on which +you can run, debug, and test your application's implementation of license +checking and enforcement. </p> + + +<h3 id="runtime-setup">Setting up the runtime environment</h3> + +<p>As described earlier, applications check licensing status not by contacting +the licensing server directly, but by binding to a service provided by the +Google Play application and initiating a license check request. The Google +Play service then handles the direct communication with the licensing server +and finally routes the response back to your application. To debug and test +licensing in your application, you need to set up a runtime environment that +includes the necessary Google Play service, so that your application is able +to send license check requests to the licensing server. </p> + +<p>There are two types of runtime environment that you can use: </p> + +<ul> +<li>An Android-powered device that includes the Google Play application, or</li> +<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2) +or higher</li> +</ul> + +<h4 id="runtime-device">Running on a device</h4> + +<p>To use an Android-powered device for +debugging and testing licensing, the device must:</p> + +<ul> +<li>Run a compatible version of Android 1.5 or later (API level +3 or higher) platform, <em>and</em> </li> +<li>Run a system image on which the Google Play client application +is preinstalled. </li> +</ul> + +<p>If Google Play is not preinstalled in the system image, your application won't +be able to communicate with the Google Play licensing server. </p> + +<p>For general information about how to set up a device for use in developing +Android applications, see <a +href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p> + +<h4 id="runtime-emulator">Running on an Android emulator</h4> + +<p>If you don't have a device available, you can use an Android emulator for debugging and testing +licensing.</p> + +<p>Because the Android platforms provided in the Android SDK <em>do +not</em> include Google Play, you need to download the Google APIs Add-On +platform, API level 8 (or higher), from the SDK repository. After downloading +the add-on, you need to create an AVD configuration that uses that system image. +</p> + +<p>The Google APIs Add-On does not include the full Google Play client. +However, it does provide: </p> + +<ul> +<li>An Google Play background service that implements the +<code>ILicensingService</code> remote interface, so that your application can +send license checks over the network to the licensing server. </li> +<li>A set of underlying account services that let you add an a Google account on +the AVD and sign in using your publisher account or test account credentials. +<p>Signing in using your publisher or test account enables you to debug and test +your application without having publish it. For more information see <a +href="#acct-signin">Signing in to an authorized account</a>, below.</p></li> +</ul> + +<p>Several versions of the Google APIs add-on are available through the SDK Manager, but only +the version for Android 2.2 and higher includes the necessary Google +Play services.</p> + +<p>To set up an emulator for adding licensing to an application, follow +these steps: </p> + +<ol> + <li>Launch the Android SDK Manager (available under the Eclipse <strong>Window</strong> +menu or by executing {@code <sdk>/tools/android sdk}).</li> + <li>Select and download <strong>Google APIs</strong> for the Android version you'd like to target +(must be Android 2.2 or higher).</li> + <li>When the download is complete, open the AVD Manager (available under the Eclipse +<strong>Window</strong> +menu or by executing {@code <sdk>/tools/android avd}).</li> + <li>Click +<strong>New</strong> and set the configuration details for the new AVD. </li> + <li>In the dialog that appears, assign a descriptive name to the AVD and then +use the Target menu to choose the <strong>Google APIs</strong> as +the system image to run on the new AVD. Set the other configuration details as +needed and then click <strong>Create AVD</strong> to finish. The SDK tools +create the new AVD configuration, which then appears in the list of available +Android Virtual Devices.</li> +</ol> + +<p>If you are not familiar with AVDs or how to use them, see <a +href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> + +<h4 id="project-update">Updating your project configuration</h4> + +<p>After you set up a runtime environment that meets the requirements described +above — either on an actual device or on an emulator — make sure to +update your application project or build scripts as needed, so that your compiled +<code>.apk</code> files that use licensing are deployed into that environment. +In particular, if you are developing in Eclipse, make sure that you set up a +Run/Debug Configuration that targets the appropriate device or AVD. </p> + +<p>You do not need to make any changes to your application's +build configuration, provided that the project is already configured to compile +against a standard Android 1.5 (API level 3) or higher library. For example: + +<ul> +<li>If you have an existing application that is compiled against +the Android 1.5 library, you do not need to make any changes to your +build configuration to support licensing. The build target meets the minimum +requirements for licensing, so you would continue building +against the same version of the Android platform.</li> + +<li>Similarly, if you are building against Android 1.5 (API level 3) but +are using an emulator running the Google APIs Add-On API 8 as the application's +runtime environment, there is no need to change your application's build +configuration. </li> +</ul> + +<p>In general, adding licensing to an application should have no impact +whatsoever on the application's build configuration.</p> + + +<h3 id="download-lvl">Downloading the LVL</h3> + +<p>The License Verification Library (LVL) is a collection of helper classes that +greatly simplify the work that you need to do to add licensing to your +application. In all cases, we recommend that you download the LVL and use it as +the basis for the licensing implementation in your application.</p> + +<p>The LVL is available as a downloadable package of the Android SDK. The +package includes: </p> + +<ul> +<li>The LVL sources, stored inside an Android library project. </li> +<li>An example application called "sample" that depends on the LVL library +project. The example illustrates how an application uses the library helper +classes to check and enforce licensing.</li> +</ul> + +<p>To download the LVL package into your development environment, use the +Android SDK Manager. Launch the Android SDK Manager and then +select the <strong>Google Market Licensing</strong> package, as shown in figure 2. +Accept the terms and click <strong>Install Selected</strong> to begin the download. </p> + +<img src="{@docRoot}images/licensing_package.png" alt=""/> +<p class="img-caption"><strong>Figure 2.</strong> The Licensing package contains the LVL and +the LVL sample application.</p> + +<p>When the download is complete, the Android SDK Manager installs both +the LVL library project and the example application into these directories: </p> + +<p style="margin-left:2em"><code><<em>sdk</em>>/extras/google/market_licensing/library/</code> + (the LVL library project)<br /> +<code><<em>sdk</em>>/extras/google/market_licensing/sample/</code> (the example +application)</p> + +<p>If you aren't familiar with how to download packess into your SDK, see the +<a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a> +document. </p> + + +<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3> + +<p>After downloading the LVL to your computer, you need to set it up in your +development environment, either as an Android library project or by +copying (or importing) the library sources directly into your existing +application package. In general, using the LVL as a library project is recommended, +since it lets you reuse your licensing code across multiple applications and +maintain it more easily over time. Note that the LVL is not designed to be +compiled separately and added to an application as a static .jar file. </p> + +<h4>Moving the library sources to a new location</h4> + +<p>Because you will be customizing the LVL sources to some extent, you should +make sure to <em>move or copy</em> the library sources (the entire +directory at <code><<em>sdk</em>>/market_licensing/library/</code>) +to a working directory outside of the SDK. You should then use the relocated +sources as your working set. If you are using a source-code management +system, add and track the sources that are in the working location rather +than those in default location in the SDK. </p> + +<p>Moving the library sources is important is because, when you later update the +Licensing package, the SDK installs the new files to the same location as +the older files. Moving your working library files to a safe location ensures +that your work won't be inadvertently overwritten should you download a new +version of the LVL.</p> + +<h4>Creating the LVL as a library project</h4> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Working with library projects</h2> + +<p>The LVL is provided as an Android library project, which means that you can +share its code and resources across multiple applications. </p> + +<p style="margin-top:.5em;">If you aren't familiar with library projects or how +to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects"> +Managing Projects</a>. +</p> +</div> +</div> + +<p>The recommended way of using the LVL is setting it up as a new Android +<em>library project</em>. A library project is a type of development project +that holds shared Android source code and resources. Other Android application +projects can reference the library project and, at build time, include its +compiled sources in their <code>.apk</code> files. In the context of licensing, +this means that you can do most of your licensing development once, in a library +project, then include the library sources in your various application projects. +In this way, you can easily maintain a uniform implementation of licensing +across all of your projects and maintain it centrally. </p> + +<p>The LVL is provided as a configured library project — once you have +downloaded it, you can start using it right away. </p> + +<p>If you are working in Eclipse with ADT, you need to add the LVL to your +workspace as a new development project, in the same way as you would a new +application project. </p> + +<ol> +<li>Use the New Project Wizard to create a new +project from existing sources. Select the LVL's <code>library</code> directory +(the directory containing the library's AndroidManifest.xml file) as the project +root.</li> +<li>When you are creating the library project, you can select any application +name, package, and set other fields as needed. </li> +<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li> +</ol> + +<p> When created, the project is +predefined as a library project in its <code>project.properties</code> file, so +no further configuration is needed. </p> + +<p>For more information about how to create an application project or work with +library projects in Eclipse, see <a +href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from +Eclipse with ADT</a>.</p> + + +<h4>Copying the LVL sources to your application</h4> + +<p>As an alternative to adding the LVL as a library project, you can copy the +library sources directly into your application. To do so, copy (or import) the +LVL's <code>library/src/com</code> directory into your application's +<code>src/</code> directory.</p> + +<p>If you add the LVL sources directly to your application, you can skip the +next section and start working with the library, as described in <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding +Licensing to Your App</a>.</p> + + +<h3 id="add-library">Including the LVL library project sources in your +application</h3> + +<p>If you want to use the LVL sources as a library project, you need to add a +reference to the LVL library project in your application project properties. This tells +build tools to include the LVL library project sources in your application at +compile time. The process for adding a reference to a library project depends +on your development environment, as described below.</p> + +<p> If you are developing in Eclipse with ADT, you should already have added the +library project to your workspace, as described in the previous section. If you +haven't done that already, do it now before continuing. </p> + +<p>Next, open the application's project properties window, as shown below. +Select the "Android" properties group and click <strong>Add</strong>, then +choose the LVL library project (com_android_vending_licensing) and click +<strong>OK</strong>. For more information, see +<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject"> +Managing Projects from Eclipse with ADT</a></p>. + + +<img src="{@docRoot}images/licensing_add_library.png" alt=""/> +<p class="img-caption"><strong>Figure 3.</strong> If you are +working in Eclipse with ADT, you can add the LVL library project to your +application from the application's project properties.</p> + + +<p>If you are developing using the SDK command-line tools, navigate to the +directory containing your application project and open the +<code>project.properties</code> file. Add a line to the file that specifies the +<code>android.library.reference.<n></code> key and the path to the +library. For example: </p> + +<pre>android.library.reference.1=path/to/library_project</pre> + +<p>Alternatively, you can use this command to update the project +properties, including the reference to the library project:</p> + +<pre class="no-pretty-print" style="color:black">android update lib-project +--target <em><target_ID></em> \ +--path <em>path/to/my/app_project</em> \ +--library <em>path/to/my/library_project</em> +</pre> + +<p>For more information about working with library projects, +see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject"> +Setting up a Library Project</a>.</p> + + + + + + + + + + + + + + + + + + + + + +<h2 id="test-env">Setting Up the Testing Environment</h2> + +<p>The Google Play publisher site provides configuration tools that let you +and others test licensing on your application before it is published. As you are +implementing licensing, you can make use of the publisher site tools to test +your application's Policy and handling of different licensing responses and +error conditions.</p> + +<p>The main components of the test environment for licensing include: </p> + +<ul> +<li>A "Test response" configuration in your publisher account that lets you +set the static licensing response returned, when the server processes a +license check for an application uploaded to the publisher account, from a user +signed in to the publisher account or a test account.</li> +<li>An optional set of test accounts that will receive the static test +response when they check the license of an application that you have uploaded +(regardless whether the application is published or not).</li> +<li>A runtime environment for the application that includes the Google Play +application or Google APIs Add-On, on which the user is signed in to the +publisher account or one of the test accounts.</li> +</ul> + +<p>Setting up the test environment properly involves:</p> + +<ol> +<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li> +<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li> +<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li> +</ol> + +<p>The sections below provide more information.</p> + + +<h3 id="test-response">Setting test responses for license checks</h3> + +<p>Google Play provides a configuration setting in your publisher account +that lets you override the normal processing of a license check and return a +specified static response code. The setting is for testing only and applies +<em>only</em> to license checks for applications that you have uploaded, made by +any user signed in to an emulator or device using the credentials of the +publisher account or a registered test account. For other users, the server +always processes license checks according to normal rules. </p> + +<p>To set a test response for your account, sign in to your publisher account +and click "Edit Profile". In the Edit Profile page, locate the Test Response +menu in the Licensing panel, shown below. You can select from the full set of +valid server response codes to control the response or condition you want to +test in your application.</p> + +<p>In general, you should make sure to test your application's licensing +implementation with every response code available in the Test Response menu. +For a description of the codes, see <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> in the <a +href="{@docRoot}guide/market/licensing/licensing-reference.html">Licensing Reference</a>.</p> + +<img src="{@docRoot}images/licensing_test_response.png" alt=""/> +<p class="img-caption"><strong>Figure 4.</strong> The Licensing +panel of your account's Edit Profile page, showing the Test Accounts field and the +Test Response menu.</p> + +<p>Note that the test response that you configure applies account-wide — +that is, it applies not to a single application, but to <em>all</em> +applications associated with the publisher account. If you are testing multiple +applications at once, changing the test response will affect all of those +applications on their next license check (if the user is signed in to +the emulator or device using the publisher account or a test account).</p> + +<p>Before you can successfully receive a test response for a license check, +you must sign in to the device or emulator on which the application +is installed, and from which it is querying the server. Specifically, you must +sign using either your publisher account or one of the test accounts that you +have set up. For more information about test accounts, see the next section.</p> + +<p>See <a +href="{@docRoot}guide/market/licensing/licensing-reference.html#server-response-codes">Server +Response Codes</a> for a list of +test responses available and their meanings. </p> + + +<h3 id="test-acct-setup">Setting up test accounts</h3> + +<p>In some cases, you might want to let multiple teams of developers test +licensing on applications that will ultimately be published through your +publisher account, but without giving them access to your publisher account's +sign-in credentials. To meet that need, the Google Play publisher site lets +you set up one or more optional <em>test accounts</em> — accounts that are +authorized to query the licensing server and receive static test responses from +your publisher account.</p> + +<p>Test accounts are standard Google accounts that you register on your +publisher account, such that they will receive the test response for +applications that you have uploaded. Developers can then sign in to their +devices or emulators using the test account credentials and initiate license +checks from installed applications. When the licensing server receives a license +check from a user of a test account, it returns the static test response +configured for the publisher account. </p> + +<p>Necessarily, there are limitations on the access and permissions given to +users signed in through test accounts, including:</p> + +<ul> +<li>Test account users can query the licensing server only for applications that +are already uploaded to the publisher account. </li> +<li>Test account users do not have permission to upload applications to your +publisher account.</li> +<li>Test account users do not have permission to set the publisher account's +static test response.</li> +</ul> + +<p>The table below summarizes the differences in capabilities, between the +publisher account, a test account, and any other account.</p> + +<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong> +Differences in account types for testing licensing.</p> + +<table> +<tr> +<th>Account Type</th> +<th>Can check license before upload?</th> +<th>Can receive test response?</th> +<th>Can set test response?</th> +</tr> + +<tr> +<td>Publisher account</td> +<td>Yes</td> +<td>Yes</td> +<td>Yes</td> +</tr> + +<tr> +<td>Test account</td> +<td>No</td> +<td>Yes</td> +<td>No</td> +</tr> + +<tr> +<td>Other</td> +<td>No</td> +<td>No</td> +<td>No</td> +</tr> +</table> + +<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4> + +<p>To get started, you need to register each test account in your publisher +account. As shown in Figure 4, you +register test accounts in the Licensing panel of your publisher account's Edit +Profile page. Simply enter the accounts as a comma-delimited list and click +<strong>Save</strong> to save your profile changes.</p> + +<p>You can use any Google account as a test account. If you want to own and +control the test accounts, you can create the accounts yourself and distribute +the credentials to your developers or testers.</p> + +<h4 id="test-app-upload">Handling application upload and distribution for test +account users</h4> + +<p>As mentioned above, users of test accounts can only receive static test +responses for applications that are uploaded to the publisher account. Since +those users do not have permission to upload applications, as the publisher you +will need to work with those users to collect apps for upload and distribute +uploaded apps for testing. You can handle collection and distribution in any way +that is convenient. </p> + +<p>Once an application is uploaded and becomes known to the licensing server, +developers and testers can continue modify the application in their local +development environment, without having to upload new versions. You only need to +upload a new version if the local application increments the +<code>versionCode</code> attribute in the manifest file. </p> + +<h4 id="test-key">Distributing your public key to test account users</h4> + +<p>The licensing server handles static test responses in the normal way, +including signing the license response data, adding extras parameters, and so +on. To support developers who are implementing licensing using test accounts, +rather than the publisher account, you will need to distribute +your public key to them. Developers without access to the publisher site do not +have access to your public key, and without the key they won't be able to +verify license responses. </p> + +<p>Note that if you decide to generate a new licensing key pair for your account +for some reason, you need to notify all users of test accounts. For +testers, you can embed the new key in the application package and distribute it +to users. For developers, you will need to distribute the new key to them +directly. </p> + + +<h3 id="acct-signin">Signing in to an authorized account in the runtime +environment</h3> + +<p>The licensing service is designed to determine whether a given user is +licensed to use a given application — during a license check, the Google +Play application gathers the user ID from the primary account on the system +and sends it to the server, together with the package name of the application +and other information. However, if there is no user information available, the +license check cannot succeed, so the Google Play application terminates the +request and returns an error to the application. </p> + +<p>During testing, to ensure that your application can successfully query the +licensing server, you must make sure that you sign in to an account <em>on the +device or emulator</em> using:</p> + +<ul> +<li>The credentials of a publisher account, or</li> +<li>The credentials of a test account that is registered with a publisher +account</li> +</ul> + + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Signing in to a Google account on an emulator</h2> + +<p>If you are testing licensing on an emulator, you need to sign in to a Google +account on the emulator. If you do not see an option to create a new Google +account, the problem might be that your AVD is running a standard Android system +image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p> + +<p style="margin-top:.5em;">For more information, see <a +href="#runtime-setup">Setting up the runtime environment</a>, above.</p> + +</div> +</div> + +<p>Signing in using a publisher account offers the advantage of letting your +applications receive static test responses even before the applications are +uploaded to the publisher site.</p> + +<p>If you are part of a larger organization or are working with external groups +on applications that will be published through your site, you will more likely +want to distribute test accounts instead, then use those to sign in during +testing. </p> + +<p>To sign in on a device or emulator, follow the steps below. The preferred +approach is to sign in as the primary account — however, if there are +other accounts already in use on the device or emulator, you can create an +additional account and sign in to it using the publisher or test account +credentials. </p> + +<ol> +<li>Open Settings > Accounts & sync</li> +<li>Select <strong>Add Account</strong> and choose to add a Google account. +</li> +<li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li> +<li>Enter the username and password of either the publisher account or a test +account that is registered in the publisher account.</li> +<li>Select <strong>Sign in</strong>. The system signs you in to the new +account.</li> +</ol> + +<p>Once you are signed in, you can begin testing licensing in your application +(if you have completed the LVL integration steps above). When your application +initiates a license check, it will receive a response containing the static test +response configured on the publisher account. </p> + +<p>Note that, if you are using an emulator, you will need to sign in to the +publisher account or test account each time you wipe data when restarting the +emulator.</p> + +<p>Once you've completed the setup procedures, continue to <a +href="{@docRoot}guide/market/licensing/adding-licensing.html">Adding Licensing to Your App</a>.</p> + + + diff --git a/docs/html/guide/market/publishing/multiple-apks.jd b/docs/html/guide/market/publishing/multiple-apks.jd index ff70e85..e7cfa33 100644 --- a/docs/html/guide/market/publishing/multiple-apks.jd +++ b/docs/html/guide/market/publishing/multiple-apks.jd @@ -45,7 +45,7 @@ support all desired devices with a single APK</li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> <li><a href="{@docRoot}sdk/compatibility-library.html">Compatibility Package</a></li> @@ -55,10 +55,10 @@ Package</a></li> </div> </div> -<p>Multiple APK support is a feature in Android Market that allows you to publish different APKs +<p>Multiple APK support is a feature on Google Play that allows you to publish different APKs for your application that are each targeted to different device configurations. Each APK is a complete and independent version of your application, but they share the same application listing on -Android Market and must share the same package name and be signed with the same release key. This +Google Play and must share the same package name and be signed with the same release key. This feature is useful for cases in which your application cannot reach all desired devices with a single APK.</p> @@ -73,8 +73,8 @@ prevent a single APK from working on all devices.</p> <p>Although <strong>we encourage you to develop and publish a single APK</strong> that supports as many device configurations as possible, doing so is sometimes not possible. To help -you publish your application for as many devices as possible, Android Market allows you to -publish multiple APKs under the same application listing. Android Market then supplies each APK to +you publish your application for as many devices as possible, Google Play allows you to +publish multiple APKs under the same application listing. Google Play then supplies each APK to the appropriate devices based on configuration support you've declared in the manifest file of each APK.</p> @@ -86,7 +86,7 @@ APK.</p> <li>Support different platform versions with each APK.</li> </ul> -<p>Currently, these are the only device characteristics that Android Market supports for publishing +<p>Currently, these are the only device characteristics that Google Play supports for publishing multiple APKs as the same application.</p> <p class="note"><strong>Note:</strong> You should generally use multiple APKs to support @@ -100,8 +100,8 @@ consider your options before publishing multiple APKs.</p> <h2 id="Concepts">Publishing Concepts</h2> -<p>Before you start publishing multiple APKs on Android Market, you must understand a few -concepts regarding how the Android Market publisher site works.</p> +<p>Before you start publishing multiple APKs on Google Play, you must understand a few +concepts regarding how the Google Play publisher site works.</p> <h3 id="Active">Active APKs</h3> @@ -111,20 +111,20 @@ concepts regarding how the Android Market publisher site works.</p> <p>When editing your application, there are two buttons on the top-right side of the page. The first button is either <strong>Publish</strong> or <strong>Unpublish</strong> and the second button is always <strong>Save</strong> (but its behavior changes).</p> - <p>When your application is new or you have unpublished it from Market, the first + <p>When your application is new or you have unpublished it from Google Play, the first button says <strong>Publish</strong>. Clicking it will publish any APKs listed as -Active, making them available on Android Market. Also while your application is new +Active, making them available on Google Play. Also while your application is new or unpublished, clicking <strong>Save</strong> will save any changes you've made, such as information added to the Product details and APKs you've uploaded, but nothing is made visible on -Android Market—this allows you to save your changes and sign out of the publisher site before +Google Play—this allows you to save your changes and sign out of the publisher site before deciding to publish.</p> <p>Once you've published your application, the first button changes to <strong>Unpublish</strong>. Clicking it in this state unpublishes your application so that none -of the APKs are available on Android Market. Also while published, the behavior of the +of the APKs are available on Google Play. Also while published, the behavior of the <strong>Save</strong> button is different. In this state, clicking <strong>Save</strong> not -only saves all your changes, but also publishes them to Android Market. For example, if you've +only saves all your changes, but also publishes them to Google Play. For example, if you've already published your application and then make changes to your product details or activate new -APKs, clicking <strong>Save</strong> makes all those changes live on Android Market.</p> +APKs, clicking <strong>Save</strong> makes all those changes live on Google Play.</p> </div> </div> @@ -135,14 +135,14 @@ moves into the list of <em>Active</em> APKs. This list allows you to preview whi you're about to publish.</p> <p>If there are no errors, any "active" APK will be published to -Android Market when you click the <strong>Publish</strong> button (if the application is +Google Play when you click the <strong>Publish</strong> button (if the application is unpublished) or when you click the <strong>Save</strong> button (if the application is already published).</p> <h3 id="SimpleAndAdvanced">Simple mode and advanced mode</h3> -<p>The Android Market publisher site provides two modes for managing the APKs associated with +<p>The Google Play publisher site provides two modes for managing the APKs associated with your application: <em>simple mode</em> and <em>advanced mode</em>. You can switch between these by clicking the link at the top-right corner of the <strong>APK files</strong> tab.</p> @@ -164,21 +164,21 @@ below.</p> <h2 id="HowItWorks">How Multiple APKs Work</h2> -<p>The concept for using multiple APKs on Android Market is that you have just one entry in -Android Market for your application, but different devices might download a different APK. This +<p>The concept for using multiple APKs on Google Play is that you have just one entry in +Google Play for your application, but different devices might download a different APK. This means that:</p> <ul> <li>You maintain only one set of product details (app description, icons, screenshots, etc.). This also means you <em>cannot</em> charge a different price for different APKs.</li> - <li>All users see only one version of your application on Android Market, so they are not + <li>All users see only one version of your application on Google Play, so they are not confused by different versions you may have published that are "for tablets" or "for phones."</li> <li>All user reviews are applied to the same application listing, even though users on different devices may have different APKs.</li> <li>If you publish different APKs for different versions of Android (for different API levels), then when a user's device receives a system update that qualifies them for a different APK you've -published, Android Market updates the user's application to the APK designed for the higher version +published, Google Play updates the user's application to the APK designed for the higher version of Android. Any system data associated with the application is retained (the same as with normal application updates when using a single APK).</li> </ul> @@ -192,8 +192,8 @@ following sections describe more about how it works.</p> <h3 id="SupportedFilters">Supported filters</h3> <p>Which devices receive each APK is determined by <a -href="{@docRoot}guide/appendix/market-filters.html">Android Market filters</a> that are specified by -elements in the manifest file of each APK. However, Android Market allows you to publish multiple +href="{@docRoot}guide/appendix/market-filters.html">Google Play filters</a> that are specified by +elements in the manifest file of each APK. However, Google Play allows you to publish multiple APKs only when each APK uses filters to support a variation of the following device characteristics:</p> @@ -229,7 +229,7 @@ with a single APK.</p> href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element are "true" if you do not declare them otherwise. However, because the {@code android:xlargeScreens} attribute was added in Android 2.3 (API level -9), Android Market will assume that it is "false" if your application does not set either <a +9), Google Play will assume that it is "false" if your application does not set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code @@ -266,7 +266,7 @@ with a higher <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min android:minSdkVersion}</a> value must have a higher <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> value. This is also true if two APKs overlap their device support based on a different supported -filter. This ensures that when a device receives a system update, Android Market can offer the user +filter. This ensures that when a device receives a system update, Google Play can offer the user an update for your application (because updates are based on an increase in the app version code). This requirement is described further in the section below about <a href="#Rules">Rules for multiple APKs</a>.</li> @@ -286,8 +286,8 @@ higher, as per the previous note).</li> </ul> <p>Other manifest elements that enable <a -href="{@docRoot}guide/appendix/market-filters.html">Android Market filters</a>—but are not -listed above—are still applied for each APK as usual. However, Android Market does not allow +href="{@docRoot}guide/appendix/market-filters.html">Google Play filters</a>—but are not +listed above—are still applied for each APK as usual. However, Google Play does not allow you to publish multiple APKs based on variations of them. Thus, you cannot publish multiple APKs if the above listed filters are the same for each APK (but the APKs differ based on other characteristics in the manifest file). For @@ -312,7 +312,7 @@ android:versionCode}</a> attribute.</li> <li>Each APK <strong>must not exactly match the configuration support of another APK</strong>. <p>That is, each APK must declare slightly different support for at least one of -the <a href="#MarketFiltersSupported">supported Market filters</a> (listed above).</p> +the <a href="#SupportedFilters">supported Google Play filters</a> (listed above).</p> <p>Usually, you will differentiate your APKs based on a specific characteristic (such as the supported texture compression formats), and thus, each APK will declare support for different devices. However, it's OK to publish multiple APKs that overlap their support slightly. When two @@ -330,11 +330,11 @@ application.</li> <li>An APK that requires a <strong>higher API level</strong> must have a <strong>higher version code</strong>. <p>This is true only when either: the APKs differ based <em>only</em> on the -supported API levels (no other <a href="#SupportedMarketFilters">supported market filters</a> +supported API levels (no other <a href="#SupportedFilters">supported filters</a> distinguish the APKs from each other) <em>or</em> when the APKs do use another supported filter, but there is an overlap between the APKs within that filter.</p> <p>This is important because a user's device receives an application update from -Android Market only if the version code for the APK on Android Market is higher than the version +Google Play only if the version code for the APK on Google Play is higher than the version code of the APK currently on the device. This ensures that if a device receives a system update that then qualifies it to install the APK for higher API levels, the device receives an application update because the version code increases.</p> @@ -365,7 +365,7 @@ increase from the lower API level to the higher API level.</li> </ul> -<p>Failure to abide by the above rules results in an error on the Android Market publisher site +<p>Failure to abide by the above rules results in an error on the Google Play publisher site when you activate your APKs—you will be unable to publish your application until you resolve the error.</p> @@ -377,7 +377,7 @@ in warnings rather than errors. Warnings can be caused by the following:</p> APKs support the devices that then fall outside the supported range. For example, if an APK currently supports small and normal size screens and you change it to support only small screens, then you have shrunk the pool of supported devices and some devices will no longer see your -application in Android Market. You can resolve this by adding another APK that supports normal size +application on Google Play. You can resolve this by adding another APK that supports normal size screens so that all previously-supported devices are still supported.</li> <li>When there are "overlaps" between two or more APKs. For example, if an APK supports screen @@ -467,8 +467,8 @@ user visible version assigned to <a href="{@docRoot}guide/topics/manifest/manifest-element.html#vname">{@code android:versionName}</a>), so that it's easy for you to associate the version code and version name.</p> -<p class="note"><strong>Note:</strong> When you increase the version code for an APK, Android -Market will prompt users of the previous version to update the application. Thus, to avoid +<p class="note"><strong>Note:</strong> When you increase the version code for an APK, Google +Play will prompt users of the previous version to update the application. Thus, to avoid unnecessary updates, you should not increase the version code for APKs that do not actually include changes.</p> @@ -507,7 +507,7 @@ configuration support for one or several of the APKs.</p> <h2 id="SingleAPK">Using a Single APK Instead</h2> <p><strong>Creating multiple APKs for your application is not the normal procedure</strong> for -publishing an application on Android Market. In most cases, you should be able to publish your +publishing an application on Google Play. In most cases, you should be able to publish your application to most users with a single APK and we encourage that you do so. When you encounter a situation in which using a single APK becomes difficult, you should carefully consider all your options before deciding to publish multiple APKs.</p> @@ -542,7 +542,7 @@ setup, the user receives your application and it runs using the resources optimi For example, on a new tablet, the user receives your application and it runs with your tablet-optimized resources. This restore process does not work across different APKs, because each APK can potentially have different -permissions that the user has not agreed to, so Android Market may not restore the application at +permissions that the user has not agreed to, so Google Play may not restore the application at all. (If you use multiple APKs, the user receives either the exact same APK if it's compatible or nothing at all and must manually download your application to get the APK designed for the new device.)</p></li> @@ -586,7 +586,7 @@ public void onSurfaceChanged(GL10 gl, int w, int h) { <h3 id="ScreenOptions">Supporting multiple screens</h3> -<p>Unless your APK file exceeds the Android Market size limit of 50MB, supporting multiple screens +<p>Unless your APK file exceeds the Google Play size limit of 50MB, supporting multiple screens should always be done with a single APK. Since Android 1.6, the Android system manages most of the work required for your application to run successfully on a variety of screen sizes and densities.</p> diff --git a/docs/html/guide/practices/compatibility.jd b/docs/html/guide/practices/compatibility.jd index bb7a72e..5e514c4 100644 --- a/docs/html/guide/practices/compatibility.jd +++ b/docs/html/guide/practices/compatibility.jd @@ -7,7 +7,7 @@ page.title=Android Compatibility <h2>See also</h2> <ol> <li><a -href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></li> +href="{@docRoot}guide/appendix/market-filters.html">Filtering on Google Play</a></li> <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing Alternative Resources</a></li> <li><a @@ -39,7 +39,7 @@ variety of hardware.</p> your apps to do that, while at the same time letting you maintain control of what types of devices your app is available to. With a bit of forethought and some minor changes in your app's manifest file, you can ensure that users -whose devices can’t run your app will never see it in the Android Market, and +whose devices can’t run your app will never see it on Google Play, and will not get in trouble by downloading it. This page explains how you can control which devices have access to your apps, and how to prepare your apps to make sure they reach the right audience.</p> @@ -64,7 +64,7 @@ every class and every API for that API level.</p> corresponding hardware or feature. But that’s not a problem: we also designed Android to prevent apps from being visible to devices which don’t have features the apps require. We’ve built support for this right into the SDK tools, and -it’s part of the Android platform itself, as well as Android Market.</p> +it’s part of the Android platform itself, as well as part of Google Play.</p> <p>As a developer, you have complete control of how and where your apps are available. Android provides tools as a first-class part of the platform that let @@ -79,9 +79,9 @@ only the devices capable of running them.</p> <li>You state the features your app requires by declaring <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses-feature></code></a> elements its manifest file.</li> -<li>Devices are required to declare the features they include to Android -Market.</li> -<li>Android Market uses your app’s stated requirements to filter it from devices +<li>Devices are required to declare the features they include to Google +Play.</li> +<li>Google Play uses your app’s stated requirements to filter it from devices that don’t meet those requirements.</li> </ol> @@ -103,24 +103,24 @@ instead use the fine-grained controls Android provides.</p> <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Filtering on Android Market</p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;">Filtering on Google Play</p> - <p>Android Market filters the applications that are visible to users, so + <p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their devices.</p> - <p style="margin-top:1em;">One of the ways Market filters applications is by -feature compatibility. To do this, Market checks the + <p style="margin-top:1em;">One of the ways Google Play filters applications is by +feature compatibility. To do this, Google Play checks the <code><uses-feature></code> elements in each application's manifest, to -establish the app's feature needs. Market then shows or hides the application to +establish the app's feature needs. Google Play then shows or hides the application to each user, based on a comparison with the features available on the user's device. <p style="margin-top:1em;">For information about other filters that you can use to control the availability of your apps, see the -<a href="{@docRoot}guide/appendix/market-filters.html">Market -Filters</a> document.</p> +<a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> +document.</p> </div> </div> @@ -142,8 +142,8 @@ future versions, new feature IDs will be added as well.</p> <p>When you write your application, you specify which features your app requires by listing their feature IDs in <code><uses-feature></code> elements in -the <code>AndroidManifest.xml</code> file. This is the information that Android -Market uses to match your app to devices that can run it. For instance, if you +the <code>AndroidManifest.xml</code> file. This is the information that Google +Play uses to match your app to devices that can run it. For instance, if you state that your app requires android.software.live_wallpapers, it won’t be shown to devices that don’t support Live Wallpapers.</p> @@ -170,12 +170,12 @@ audience size and minimizing development costs.</p> business or legal reasons. For instance, an app that displays train schedules for the London Underground is unlikely to be useful to users outside the United Kingdom. Other apps might not be permitted in certain countries for business or -legal reasons. For cases such as these, Android Market itself provides +legal reasons. For cases such as these, Google Play itself provides developers with filtering options that allow them control their app’s availability for non-technical reasons.</p> -<p>The help information for Android Market provides full details, but in a -nutshell, developers can use the Market publisher UI to:</p> +<p>The help information for Google Play provides full details, but in a +nutshell, developers can use the Google Play publisher UI to:</p> <ul> <li>List the countries an app is available in.</li> @@ -185,7 +185,7 @@ nutshell, developers can use the Market publisher UI to:</p> <p>Filtering for technical compatibility (such as required hardware components) is always based on information contained within your <code>.apk</code> file. But filtering for non-technical reasons (such as geographic restrictions) is always -handled in the Market user interface.</p> +handled in the Google Play user interface.</p> <h3 id="futureproofing">Future-proofing</h3> @@ -206,7 +206,7 @@ capability, though a (fixed-focus) camera was still required. Some apps such as barcode scanners do not function as well with cameras that do not auto-focus. To prevent users from having a bad experience with those apps, existing apps that obtain permission to use the Camera were assumed by default to require -auto-focus. This allowed Android Market to filter those apps from devices that +auto-focus. This allowed Google Play to filter those apps from devices that lack auto-focus.</li> <li>Android 2.2, meanwhile, allowed the microphone to be optional on some diff --git a/docs/html/guide/practices/design/accessibility.html b/docs/html/guide/practices/design/accessibility.html new file mode 100644 index 0000000..0fa7b32 --- /dev/null +++ b/docs/html/guide/practices/design/accessibility.html @@ -0,0 +1,11 @@ +<html> +<head> +<meta http-equiv="refresh" +content="0;url=http://developer.android.com/guide/topics/ui/accessibility/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should be redirected. Please <a +href="http://developer.android.com/guide/topics/ui/accessibility/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/practices/design/accessibility.jd b/docs/html/guide/practices/design/accessibility.jd deleted file mode 100644 index a66a974..0000000 --- a/docs/html/guide/practices/design/accessibility.jd +++ /dev/null @@ -1,353 +0,0 @@ -page.title=Designing for Accessibility -@jd:body - - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>To make your application more accessible, you should make sure your UI is navigable -using a directional controller and your widgets provide content descriptions</li> - <li>If you implement a custom view, you should ensure that it delivers the appropriate -accessibility events during user interaction</li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#Navigation">Allow Navigation with a Directional Controller</a> - <ol> - <li><a href="#FocusOrder">Controlling focus order</a></li> - <li><a href="#ClickingDpad">Clicking with a directional controller</a></li> - </ol> - </li> - <li><a href="#LabelInputs">Label Your Input Widgets</a></li> - <li><a href="#UiBestPractices">Follow Android UI Best Practices</a></li> - <li><a href="#CustomViews">Send Accessibility Events from Custom View Components</a></li> - <li><a href="#Test">Test Your Application’s Accessibility</a></li> - </ol> - - <h2>Key classes</h2> - <ol> - <li>{@link android.view.accessibility.AccessibilityEvent}</li> - <li>{@link android.view.accessibility.AccessibilityEventSource}</li> - </ol> - - <h2>Related samples</h2> - <ol> - <li><a -href="{@docRoot}resources/samples/AccessibilityService/index.html">Accessibility Service</a></li> - </ol> - -</div> -</div> - - - -<p>Many Android users have disabilities that require them to interact with their Android devices in -different ways. These include users who have visual, physical or age-related disabilities that -prevent them from fully using or seeing a touchscreen.</p> - -<p>Android provides an accessibility layer that helps these users navigate their Android-powered -devices more easily. Android's accessibility services provide things like text-to-speech, haptic -feedback, and trackball/d-pad navigation that augment the user experience.</p> - -<p>Your application should follow the guidelines in this document to ensure that it provides a -good experience for users with disabilities. Following these two basic rules will solve most -access-related problems:</p> - -<ul> -<li>Make all of your user interface controls accessible with a trackball or directional -controller (d-pad).</li> -<li>Label your {@link android.widget.ImageButton}, {@link android.widget.EditText}, and other input -widgets using the <a -href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription">{@code -android:contentDescription}</a> attribute.</li> -</ul> - - - -<h2 id="Navigation">Allow Navigation with a Directional Controller</h2> - -<p>Many Android devices come with some sort of directional controller, such as:</p> -<ul> -<li>A clickable trackball that users can move in any direction</li> -<li>A clickable d-pad that allows users to navigate in four directions.</li> -<li>Arrow keys and an OK button that’s equivalent to clicking a trackball or d-pad.</li> -</ul> - -<p>All of these directional controllers allow users to navigate the screen without using the -touchscreen. On some devices, a user can also navigate to the top or bottom of a list by holding -down the <em>alt</em> key while pressing a discrete key for up or down.</p> - -<p>A directional controller is the primary means of navigation for users with visual or some -physical impairments (and also for users without impairments when using devices that don't -have a touchscreen). You should verify that all UI controls in your application are -accessible without using the touchscreen and that clicking with the center button (or OK button) has -the same effect as touching the controls on the touchscreen.</p> - -<p>A UI control (also called a "widget") is accessible using directional controls when it's -"focusable" property is "true." This means that users can focus on the widget using the directional -controls and then interact with it. Widgets provided by the Android APIs are focusable by default -and visually indicate focus by changing the widget visual appearance in some way.</p> - -<p>Android provides several APIs that let you control whether a widget is focusable and even -request that a widget be given focus. Such methods include:</p> - -<ul> - <li>{@link android.view.View#setFocusable setFocusable()}</li> - <li>{@link android.view.View#isFocusable isFocusable()}</li> - <li>{@link android.view.View#requestFocus requestFocus()}</li> -</ul> - -<p>When working with a view that is not focusable by default, you can make it focusable from the XML -layout file by setting the <a -href="{@docRoot}reference/android/view/View.html#attr_android:focusable">{@code -android:focusable}</a> attribute to {@code "true"}.</p> - - - -<h3 id="FocusOrder">Controlling focus order</h3> - -<p>When the user navigates in any direction using the directional controls, focus is passed from one -view to another, as determined by the focus ordering. The ordering of the focus movement is based on -an algorithm that finds the nearest neighbor in a given direction. In rare cases, the default -algorithm may not match the order that you intended for your UI. In these situations, you can -provide explicit overrides to the ordering using the following XML attributes in the layout -file:</p> - -<dl> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" ->{@code android:nextFocusDown}</a></dt> - <dd>Defines the next view to receive focus when the user navigates down.</dd> - <a><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft" ->{@code android:nextFocusLeft}</a></dt> - <dd>Defines the next view to receive focus when the user navigates left.</dd> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight" ->{@code android:nextFocusRight}</a></dt> - <dd>Defines the next view to receive focus when the user navigates right.</dd> - <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" ->{@code android:nextFocusUp}</a></dt> - <dd>Defines the next view to receive focus when the user navigates up.</dd> -</dl> - -<p>For example, here is an XML layout that contains a focusable {@link android.widget.TextView}. -While the {@link android.widget.TextView} is located to the right of the {@link -android.widget.EditText}, it can now be reached by pressing the down arrow when focus is on the -{@link android.widget.EditText}: </p> - -<pre> -<LinearLayout android:orientation="horizontal" - ... > - <EditText android:id="@+id/edit" - android:nextFocusDown=”@+id/text” - ... /> - <TextView android:id="@+id/text" - android:focusable=”true” - android:text="Hello, I am a focusable TextView" - android:nextFocusUp=”@id/edit” - ... /> -</LinearLayout> -</pre> - -<p>When modifying this ordering, be sure that the navigation works as expected in all directions -from each widget and when navigating in reverse (to get back to where you came from).</p> - -<p>You can also modify the focus ordering at runtime, using methods in the {@link -android.view.View} class, such as {@link android.view.View#setNextFocusDownId -setNextFocusDownId()} and {@link android.view.View#setNextFocusRightId -setNextFocusRightId()}.</p> - - -<h3 id="ClickingDpad">Clicking with a directional controller</h3> - -<p>On most devices, clicking a view using a directional controller sends a {@link -android.view.KeyEvent} with {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} to the view currently -in focus. Make sure this event has the same effect as touching the view on the touchscreen. All -standard Android views already handle {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} -appropriately.</p> - -<p>If possible, also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the same as -{@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. That makes interaction much easier from a full -keyboard.</p> - - - - -<h2 id="LabelInputs">Label Your Input Widgets</h2> - -<p>Many input widgets rely on visual cues to inform the user of their meaning. For example, a -notepad application might use an {@link android.widget.ImageButton} with a picture of a plus sign to -indicate that the user can add a new note. Or, an {@link android.widget.EditText} may have -a label near it that indicates its purpose. When a visually impaired user accesses your -application, these visual cues are often useless.</p> - -<p>To provide textual information about these widgets (as an alternative to the visual cues), you -should use the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription" ->{@code android:contentDescription}</a> attribute. The text you provide in this attribute -is not visible on the screen, but if a user has enabled accessibility speech tools then the -description in this attribute is read aloud to the user.</p> - -<p>You should set the <a -href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription" >{@code -android:contentDescription}</a> attribute on every {@link android.widget.ImageButton}, {@link -android.widget.EditText}, {@link android.widget.CheckBox}, and on any other input widgets that might -benefit users with extra information.</p> - -<p>For example, the following {@link android.widget.ImageButton} sets the content description for -the plus button to the {@code add_note} string resource, which might be defined in English as -“Add note":</p> - -<pre> -<ImageButton - android:id=”@+id/add_entry_button” - android:src=”@drawable/plus” - android:contentDescription=”@string/add_note”/> -</pre> - -<p>This way, when using speech accessibility tools, the user hears "Add note" when focused on -this widget.</p> - - - -<h2 id="UiBestPractices">Follow Android UI Best Practices</h2> - -<p>You can make it easier for users to learn how to use your application by developing a user -interface that complies with Android's standard interaction patterns, instead of creating your own -or using interaction patterns from another platform. This consistency is especially important for -many disabled users, as they may have less contextual information available to try to understand -your application’s interface.</p> - -<p>Specifically, you should:</p> - -<ul> -<li>Use the platform's built-in widgets and layouts whenever possible, as these views provide -accessibility support by default.</li> -<li>Use the <a href="{@docRoot}guide/topics/ui/menus.html#options-menu">Options Menu</a> as an -alternative to complex touchscreen tasks.</li> -<li>Make sure the BACK button correctly moves the user back one logical step in the <a -href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">task's back stack</a> or the -activity's back stack of fragments (when <a -href="{@docRoot}guide/topics/fundamentals/fragments.html#Transactions">performing fragment -transactions</a>), as appropriate.</li> -</ul> - - - -<h2 id="CustomViews">Send Accessibility Events from Custom View Components</h2> - -<p>If your application requires that you create a <a -href="{@docRoot}guide/topics/ui/custom-components.html">custom view component</a>, you may need to -do some additional work to ensure that your view is accessible. Specifically, you should make sure -that your view implements the {@link android.view.accessibility.AccessibilityEventSource} -interface and emits {@link android.view.accessibility.AccessibilityEvent}s at the proper times, -and that each {@link android.view.accessibility.AccessibilityEvent} contains relevant information -about the state of the view.</p> - -<p>Events are emitted whenever something notable happens in the user interface. Currently, there -are five types of accessibility events that a view should send to the system as the user interacts -with it:</p> - -<dl> -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}</dt> -<dd>Indicates that the user clicked on the view (for example, the user selects a button).</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</dt> -<dd>Indicates that the user performed a long press on the view. </dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SELECTED}</dt> -<dd>Indicates that the user selected an item from within the view. This is usually used in the -context of an {@link android.widget.AdapterView}.</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}</dt> -<dd>Indicates that the user moved the focus to the view.</dd> - -<dt>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED}</dt> -<dd>Indicates that the text or contents of the view changed.</dd> -</dl> - - -<p>The basic {@link android.view.View} class implements {@link -android.view.accessibility.AccessibilityEventSource} and emits these events at the proper time in -the standard cases. Your custom view should extend from {@link android.view.View} (or one of its -subclasses) to take advantage of these default implementations.</p> - -<p>Depending on the specifics of your custom view, your view may need to emit one of these events at -a different time than the default {@link android.view.View} implementation. To do so, simply call -{@link android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent -sendAccessibilityEvent()} with the specific event type at the correct time.</p> - -<p>For example, say you are implementing a custom slider bar that allows the user to select a -numeric value by pressing the left or right arrows. This view should emit an event of type {@link -android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider value -changes:</p> - -<pre> -@Override -public boolean onKeyUp (int keyCode, KeyEvent event) { - if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) { - mCurrentValue--; - sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); - return true; - } - ... -} -</pre> - -<p>Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that -describe the current state of the view. These properties include things like the view’s class name, -text and checked state. The specific properties required for each event type are described in the -{@link android.view.accessibility.AccessibilityEvent} documentation. The {@link android.view.View} -implementation will fill in default values for these properties. Most of these values, like the -class name and event timestamp, will not need to be changed. However, depending on the specifics of -your custom view, you may want to provide a different value for one or more of the properties. For -example, your view may have additional state information that you want to add to the event text.</p> - -<p>The {@link android.view.View#dispatchPopulateAccessibilityEvent -dispatchPopulateAccessibilityEvent()} method in {@link android.view.View} provides a hook for making -changes to the {@link android.view.accessibility.AccessibilityEvent} object before it is -emitted.</p> - -<p>In the above slider bar example, the view should add the current value of the slider bar to the -text of the event:</p> - -<pre> -@Override -public boolean dispatchPopulateAccessibilityEvent(final AccessibilityEvent event) { - super.dispatchPopulateAccessibilityEvent(event); - if (!isShown()) { - return false; - } - CharSequence text = String.valueOf(mCurrentValue); - if (text.length() > AccessibilityEvent.MAX_TEXT_LENGTH) { - text = text.subSequence(0, AccessiblityEvent.MAX_TEXT_LENGTH); - } - event.getText().add(text); - return true; -} -</pre> - - -<h2 id="Test">Test Your Application’s Accessibility</h2> - -<p>You can simulate the experience for many users by enabling an accessibility service that speaks -as you move around the screen. One such service is <a -href="https://market.android.com/details?id=com.google.android.marvin.talkback">TalkBack</a>, by the -<a href="http://code.google.com/p/eyes-free/">Eyes-Free Project</a>. It comes preinstalled on many -Android-powered devices, but is also available for free from <a -href="https://market.android.com/details?id=com.google.android.marvin.talkback">Android -Market</a>.</p> - -<p>This service requires that you have a text-to-speech engine installed on your phone. You can -verify if you have one installed in the <strong>Text-to-speech</strong> settings menu by selecting -<strong>Listen to an example</strong>. If you do not hear anything spoken, install the required -voice data by selecting <strong>Install voice data</strong>.</p> - -<p>Once text-to-speech is functioning correctly, you can enable TalkBack (or another accessibility -service) in the <strong>Accessibility</strong> settings menu. Enable both -<strong>Accessibility</strong> and <strong>TalkBack</strong>. As you navigate about the device, you -should now hear spoken feedback.</p> - -<p>You can now attempt to use your application as a blind user would. As you move around using only -the directional controller, make sure that the spoken feedback you hear makes sense and is -sufficient to navigate the application without any visual cues.</p> diff --git a/docs/html/guide/practices/optimizing-for-3.0.jd b/docs/html/guide/practices/optimizing-for-3.0.jd index 39662f1..d6c621e 100644 --- a/docs/html/guide/practices/optimizing-for-3.0.jd +++ b/docs/html/guide/practices/optimizing-for-3.0.jd @@ -108,7 +108,7 @@ SDK with the new platform:</p> SDK starter package now</a>.)</p> <ol> - <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK and AVD + <li><a href="{@docRoot}sdk/adding-components.html#launching">Launch the Android SDK Manager</a> and install the following: <ul> <li>SDK Platform Android 3.0</li> @@ -147,7 +147,7 @@ Android 3.0, the emulator is still best way to evaluate your application's appea functionality on Android 3.0.</p> <p class="note"><strong>Tip:</strong> To improve the startup time for the emulator, enable snapshots -for the AVD when you create it with the SDK and AVD Manager (there's a checkbox in the AVD creator +for the AVD when you create it with the AVD Manager (there's a checkbox in the AVD creator to <strong>Enable</strong> snapshots). Then, start the AVD from the AVD manager and check <b>Launch from snapshot</b> and <b>Save to snapshot</b>. This way, when you close the emulator, a snapshot of the AVD state is saved and used to quickly relaunch the AVD next time. However, when you choose to @@ -281,7 +281,7 @@ to help you add features from Android 3.0 without requiring you to change your < href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> or build target, we're providing a static library called the <a href="{@docRoot}sdk/compatibility-library.html">Compatibility Library</a> -(downloadable from the AVD and SDK Manager).</p> +(downloadable from the Android SDK Manager).</p> <p>This library includes APIs for <a href="{@docRoot}guide/topics/fundamentals/fragments.html">fragments</a>, <a href="{@docRoot}guide/topics/fundamentals/loaders.html">loaders</a>, and some updated classes. By @@ -421,7 +421,7 @@ href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p> href="{@docRoot}sdk/android-3.0.html#api">Android 3.0 Platform</a> document also have accompanying samples that allow you to preview the effects and can help you understand how to use them. To get the samples, download them from the SDK repository <a href="{@docRoot}sdk/adding-components.html" ->using the Android SDK and AVD Manager</a>. After downloading the samples ("Samples for SDK API +>using the Android SDK Manager</a>. After downloading the samples ("Samples for SDK API 11"), you can find them in <code><sdk_root>/samples/android-11/</code>. The following list provides links to the browsable source code for some of the samples:</p> @@ -481,7 +481,7 @@ and densities.</p> configurations of screen size and density, you can instead choose to limit the distribution of your application to certain types of screens, such as only tablets or only mobile devices. To do so, you can add elements to your Android manifest file that enable filtering based on screen configuration -by external services such as Android Market.</p> +by external services such as Google Play.</p> <p>However, before you decide to restrict your application to certain screen configurations, you should understand the techniques for <a @@ -517,14 +517,14 @@ screens, you can declare the element in your manifest like this:</p> </manifest> </pre> -<p>External services such as Android Market read this manifest element and use it to ensure that +<p>External services such as Google Play read this manifest element and use it to ensure that your application is available only to devices with an extra large screen.</p> <p class="note"><strong>Note:</strong> If you use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element for the reverse scenario (when your application is not compatible with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then -external services such as Android Market <strong>do not</strong> apply filtering. Your application +external services such as Google Play <strong>do not</strong> apply filtering. Your application will still be available to larger screens, but when it runs, it will not fill the screen—the system will draw it in a "postage stamp" window that's the same relative size as the screen size that your application does support. If you want to prevent your application from being downloaded on @@ -541,7 +541,7 @@ larger devices to download the version designed for smaller screens. In such a c use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a> element to manage the distribution of your application based on the combination of screen size and density. External services such as -Android Market uses this information to apply filtering to your application, so that only devices +Google Play uses this information to apply filtering to your application, so that only devices that have a screen configuration with which you declare compatibility can download your application.</p> @@ -551,7 +551,7 @@ which each specify a screen configuration with which your application is compati the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code <screen>} element <strong>must include both attributes</strong> to specify an individual screen configuration—if either attribute is missing, then the element is invalid -(external services such as Android Market will ignore it).</p> +(external services such as Google Play will ignore it).</p> <p>For example, if your application is compatible with only small and normal screens, regardless of screen density, then you must specify eight different {@code <screen>} elements, @@ -613,7 +613,7 @@ orientation, you should update your application to support landscape.</p></li> <li><a href="#Telephony">Not all devices have telephony or other features</a> <p>If your application declares the {@code "android.hardware.telephony"} feature in the manifest, then it will not be available to devices that do not offer telephony (such as tablets), based on -Android Market filtering. If your application can function properly without telephony, you should +Google Play filtering. If your application can function properly without telephony, you should update your application to gracefully disable the telephony features when not available on a device.</p></li> </ul> @@ -682,7 +682,7 @@ your applications. For example:</p> <pre><uses-feature android:name="android.hardware.telephony" /></pre> <p>By default, this declares that your application <em>requires</em> telephony features. So, -external services such as Android Market use this information to filter your application from +external services such as Google Play use this information to filter your application from devices that do not offer telephony.</p> <p>If, however, your application uses, but does not require the feature, you should diff --git a/docs/html/guide/practices/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd index 60c9c95..a7c4a8e 100644 --- a/docs/html/guide/practices/screens-distribution.jd +++ b/docs/html/guide/practices/screens-distribution.jd @@ -37,7 +37,7 @@ href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for And configurations of screen size and density, you can instead choose to limit the distribution of your application to certain types of screens, such as only tablets and other large devices or only handsets and similar-sized devices. To do so, you can enable filtering by external services such as -Android Market by adding elements to your manifest file that specify the screen configurations your +Google Play by adding elements to your manifest file that specify the screen configurations your application supports.</p> <p>However, before you decide to restrict your application to certain screen configurations, you @@ -58,7 +58,7 @@ might discover that your application can't scale up well or perhaps you've decid versions of your application for different screen configurations. In such a case, you can use the <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code <compatible-screens>}</a> element to manage the distribution of your application based on -combinations of screen size and density. External services such as Android Market use this +combinations of screen size and density. External services such as Google Play use this information to apply filtering to your application, so that only devices that have a screen configuration with which you declare compatibility can download your application.</p> @@ -68,7 +68,7 @@ configuration with which you declare compatibility can download your application compatible, using both the {@code android:screenSize} and {@code android:screenDensity} attributes. Each {@code <screen>} element <strong>must include both attributes</strong> to specify an individual screen configuration—if either attribute is missing, then the element is invalid -(external services such as Android Market will ignore it).</p> +(external services such as Google Play will ignore it).</p> <p>For example, if your application is compatible with only small and normal size screens, regardless of screen density, you must specify eight different {@code <screen>} elements, @@ -173,7 +173,7 @@ Tools for Managing Screen Sizes</a>.</p> href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element for the reverse scenario (when your application is not compatible with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then -external services such as Android Market <strong>do not</strong> apply filtering. Your application +external services such as Google Play <strong>do not</strong> apply filtering. Your application will still be available to larger screens, but when it runs, it will not resize to fit the screen. Instead, the system will emulate a handset screen size (about 320dp x 480dp; see <a href="{@docRoot}guide/practices/screen-compat-mode.html">Screen Compatibility Mode</a> for more @@ -197,13 +197,13 @@ configurations.</p> <h2 id="MultiApks">Publishing Multiple APKs for Different Screens</h2> -<p>Although we recommend that you publish one APK for your application, Android Market allows +<p>Although we recommend that you publish one APK for your application, Google Play allows you to publish multiple APKs for the same application when each APK supports a different set of screen configurations (as declared in the manifest file). For example, if you want to publish both a handset version and a tablet version of your application, but you're unable to make the same APK work for both screen sizes, you can actually publish two APKs for the same application listing. Depending on each device's -screen configuration, Android Market will deliver it the APK that you've declared to support that +screen configuration, Google Play will deliver it the APK that you've declared to support that device's screen.</p> <p>Beware, however, that publishing multiple APKs for the same application is @@ -212,5 +212,5 @@ APK that can support a wide range of device configurations</strong>. Supporting sizes, especially, is within reason using a single APK, as long as you follow the guide to <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p> -<p>If you need more information about how to publish multiple APKs on Android Market, read <a +<p>If you need more information about how to publish multiple APKs on Google Play, read <a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index fb121bd..a870b22 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -882,8 +882,8 @@ application requires is the smallest possible on any device.</p> <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this attribute, so it does not affect how your application behaves at runtime. Instead, it is used -to enable filtering for your application on services such as Android Market. However, -<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +to enable filtering for your application on services such as Google Play. However, +<strong>Google Play currently does not support this attribute for filtering</strong> (on Android 3.2), so you should continue using the other size attributes if your application does not support small screens.</p> </dd> @@ -1242,12 +1242,12 @@ have to buy various devices just to test your application's screen support.</p> <p>To set up an environment for testing your application's screen support, you should create a series of AVDs (Android Virtual Devices), using emulator skins and screen configurations that emulate the screen sizes and densities you want your application to support. To do so, you can use -the Android SDK and AVD Manager to create the AVDs and launch them with a graphical interface.</p> +the AVD Manager to create the AVDs and launch them with a graphical interface.</p> -<p>To launch the Android SDK and AVD Manager, execute the {@code +<p>To launch the Android SDK Manager, execute the {@code SDK Manager.exe} from your Android SDK directory (on Windows only) or execute {@code android} from -the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the Android SDK and -AVD Manager with a selection of AVDs, for testing various screen configurations.</p> +the {@code <sdk>/tools/} directory (on all platforms). Figure 6 shows the AVD +Manager with a selection of AVDs, for testing various screen configurations.</p> <p>Table 3 shows the various emulator skins that are available in the Android SDK, which you can use to emulate some of the most common screen configurations.</p> @@ -1340,7 +1340,7 @@ dashboard.</p> <div class="figure" style="width:204px"> <img src="{@docRoot}images/screens_support/avd-start.png" alt="" /> <p class="img-caption"><strong>Figure 7.</strong> - Size and density options you can set, when starting an AVD from the Android SDK and AVD + Size and density options you can set, when starting an AVD from the AVD Manager.</p> </div> @@ -1349,12 +1349,12 @@ up to run at a physical size that closely matches an actual device. This makes it a lot easier to compare the results at various sizes and densities. To do so you need to know the approximate density, in dpi, of your computer monitor (for instance, a 30" Dell monitor has a density of about 96 dpi). When you launch an AVD -from the Android SDK and AVD Manager, you can specify the screen size for the emulator and your +from the AVD Manager, you can specify the screen size for the emulator and your monitor dpi in the Launch Options, as shown in figure 7.</p> <p>If you would like to test your application on a screen that uses a resolution or density not supported by the built-in skins, you can create an AVD that uses a custom resolution -or density. When creating the AVD from the Android SDK and AVD Manager, specify the Resolution, +or density. When creating the AVD from the AVD Manager, specify the Resolution, instead of selecting a Built-in Skin.</p> <p>If you are launching your AVD from the command line, you can specify the scale for diff --git a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd index 9be72ee..8e4528e 100644 --- a/docs/html/guide/practices/ui_guidelines/activity_task_design.jd +++ b/docs/html/guide/practices/ui_guidelines/activity_task_design.jd @@ -3,6 +3,43 @@ parent.title=UI Guidelines parent.link=index.html @jd:body + + + +<div id="deprecatedSticker"> + <a href="#" + onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> + <strong>This doc is deprecated</strong></a> +</div> + + +<div id="naMessage" style="display:block"> +<div><p><strong>This document has been deprecated.</strong></p> + <p>For information about designing an activity structure and navigation, read the design guidelines +for <a href="{@docRoot}design/patterns/app-structure.html">App Structure</a> and +<a href="{@docRoot}design/patterns/navigation.html">Navigation</a>, or the developer guide +about <a +href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks and Back Stack</a>.</p> + + <input style="margin-top:1em;padding:5px" type="button" + value="That's nice, but I still want to read this document" +onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> +</div> +</div> + + + + + + + + + + + + + + <div id="qv-wrapper"> <div id="qv"> @@ -886,7 +923,7 @@ href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Fi You can perform this test when initializing the user interface. For instance, you could disable the user control that initiates the Intent object, or display a message to the user that lets them go - to a location, such as the Market, to download its application. + to a location, such as Google Play, to download its application. In this way, your code can start the activity (using either startActivity() or startActivityForResult()) only if the intent has tested to resolve to an activity that is actually present. diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd index 6b686b1..4b6768f 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher.jd @@ -49,9 +49,9 @@ across the range of devices on which your application can be installed. See <a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#design-tips">Tips for Designers</a> for suggestions on how to work with multiple sets of icons.</p> -<p>A high-resolution version of your application launcher icon is also required by Android Market +<p>A high-resolution version of your application launcher icon is also required by Google Play for use in application listings. For more details on this, see <a -href="#icons_in_market">Application Icons in Android Market</a> below.</p> +href="#icons_in_market">Application Icons on Google Play</a> below.</p> <p class="note"><strong>Note:</strong> @@ -81,7 +81,7 @@ need to review the old guidelines, see the <ol> <li>Promote the brand and tell the story of the app.</li> - <li>Help users discover the app in Android Market.</li> + <li>Help users discover the app on Google Play.</li> <li>Function well in the Launcher.</li> </ol> @@ -100,19 +100,19 @@ app is about. Thus, you should:</p> </ul> -<h3 id="help_users_discover">Help users discover the app in Android Market</h3> +<h3 id="help_users_discover">Help users discover the app on Google Play</h3> -<p>App launcher icons are the first look that prospective users will get of your app in Android -Market. A high quality app icon can influence users to find out more as they scroll through lists of +<p>App launcher icons are the first look that prospective users will get of your app on Google Play. +A high quality app icon can influence users to find out more as they scroll through lists of applications.</p> <p>Quality matters here. A well-designed icon can be a strong signal that your app is of similarly high quality. Consider working with an icon designer to develop the app’s launcher icon.</p> -<p class="note"><strong>Note:</strong> Android Market requires a high-resolution version of your -icon; for more details on this, see <a href="#icons_in_market">Application Icons in Android -Market</a> below.</p> +<p class="note"><strong>Note:</strong> Google Play requires a high-resolution version of your +icon; for more details on this, see <a href="#icons_in_market">Application Icons in Google +Play</a> below.</p> <h3 id="function_well_in_launcher">Function well in the Launcher</h3> @@ -239,21 +239,21 @@ This padding can also be used to make room for a subtle drop shadow, which can h that launcher icons are legible across on any background color.</p> -<h3 id="icons_in_market">Application Icons in Android Market</h3> +<h3 id="icons_in_market">Application Icons on Google Play</h3> <p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing your application on -Android Market</a>, you will also need to provide a 512 x 512 pixel, high-resolution application icon -in the <a href="http://market.android.com/publish">developer console</a> at upload time. This icon -will be used in various locations in Android Market and does not replace your launcher icon.</p> +Google Play</a>, you will also need to provide a 512 x 512 pixel, high-resolution application icon +in the <a href="http://play.google.com/apps/publish">developer console</a> at upload time. This icon +will be used in various locations on Google Play and does not replace your launcher icon.</p> <p>For tips and recommendations on creating high-resolution launcher icons that can easily be scaled up to 512x512, see <a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html#design-tips"> Tips for Designers</a>.</p> -<p>For information and specifications about high-resolution application icons in Android Market, see +<p>For information and specifications about high-resolution application icons on Google Play, see the following article:</p> <p style="margin-left:2em"><a href="http://market.android.com/support/bin/answer.py?answer=1078870"> -Graphic Assets for your Application (Android Market Help) »</a> +Graphic Assets for your Application (Google Play Help) »</a> <br><br> diff --git a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd index ea036cd..85a3cc8 100644 --- a/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd +++ b/docs/html/guide/practices/ui_guidelines/icon_design_launcher_archive.jd @@ -56,13 +56,13 @@ suggestions on how to work with multiple sets of icons.</p> -<h2 id="market">Application Icons in Android Market</h2> +<h2 id="market">Application Icons on Google Play</h2> <p>If you are <a href="{@docRoot}guide/publishing/publishing.html">publishing -your application on Android Market</a>, you will also need to provide a 512x512 +your application on Google Play</a>, you will also need to provide a 512x512 pixel, high-resolution application icon in the <a -href="http://market.android.com/publish">developer console</a> at upload-time. -This icon will be used in various locations in Android Market and does +href="http://play.google.com/apps/publish">developer console</a> at upload-time. +This icon will be used in various locations on Google Play and does not replace your launcher icon.</p> <p>For tips and recommendations on creating high-resolution launcher icons that @@ -71,11 +71,11 @@ can easily be scaled up to 512x512, see Tips for Designers</a>.</p> <p>For information and specifications about high-resolution application -icons in Android Market, see the following article:</p> +icons on Google Play, see the following article:</p> <p style="margin-left:2em"><a href="http://market.android.com/support/bin/answer.py?answer=1078870"> - Graphic Assets for your Application (Android Market Help) »</a> + Graphic Assets for your Application (Google Play Help) »</a> diff --git a/docs/html/guide/practices/ui_guidelines/index.jd b/docs/html/guide/practices/ui_guidelines/index.jd index 3255275..24fb855 100644 --- a/docs/html/guide/practices/ui_guidelines/index.jd +++ b/docs/html/guide/practices/ui_guidelines/index.jd @@ -39,26 +39,6 @@ at a glance, on a user's Home screen. These design guidelines describe how to design widgets that fit with others on the Home screen. They include links to graphics files and templates that will make your designer's life easier.</dd> </dl> - <dl> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/activity_task_design.html">Activity and Task Design Guidelines</a> </dt> - <dd>Activities are the basic, independent building blocks of applications. - As you design your application's UI and feature set, you are free to - re-use activities from other applications as if they were yours, - to enrich and extend your application. These guidelines - describe how activities work, illustrates them with examples, and - describes important underlying principles and mechanisms, such as - multitasking, activity reuse, intents, the activity stack, and - tasks. It covers this all from a high-level design perspective. -</dd> - <dt><a href="{@docRoot}guide/practices/ui_guidelines/menu_design.html">Menu Design Guidelines</a> </dt> - <dd>Android applications make use of Option menus and Context menus - that enable users to perform operations and navigate to other parts - of your application or to other applications. These guidelines describe - the difference between Options anontext menus, how to arrange - menu items, when to put commands on-screen, and other details about - menu design. -</dd> -</dl> diff --git a/docs/html/guide/practices/ui_guidelines/menu_design.jd b/docs/html/guide/practices/ui_guidelines/menu_design.jd index 7576b6c..b4e2ea7 100644 --- a/docs/html/guide/practices/ui_guidelines/menu_design.jd +++ b/docs/html/guide/practices/ui_guidelines/menu_design.jd @@ -2,7 +2,38 @@ page.title=Menu Design Guidelines parent.title=UI Guidelines parent.link=index.html @jd:body + + + + +<div id="deprecatedSticker"> + <a href="#" + onclick="$('#naMessage').show();$('#deprecatedSticker').hide();return false"> + <strong>This doc is deprecated</strong></a> +</div> + + +<div id="naMessage" style="display:block"> +<div><p><strong>This document has been deprecated.</strong></p> + <p>For design guidelines about adding user actions and other options, read the design guidelines +for <a href="{@docRoot}design/patterns/actionbar.html">Action Bar</a> or the developer guide about +<a href="{@docRoot}guide/topics/ui/menus.html">Menus</a>.</p> + + <input style="margin-top:1em;padding:5px" type="button" + value="That's nice, but I still want to read this document" +onclick="$('#naMessage').hide();$('#deprecatedSticker').show()" /> +</div> +</div> + + + + + + + + + <div id="qv-wrapper"> <div id="qv"> diff --git a/docs/html/guide/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index 9abcdf7..5bd9be55 100644 --- a/docs/html/guide/publishing/app-signing.jd +++ b/docs/html/guide/publishing/app-signing.jd @@ -66,7 +66,7 @@ on an emulator or a device if it is not signed.</li> application's signer certificate expires after the application is installed, the application will continue to function normally.</li> <li>You can use standard tools — Keytool and Jarsigner — to generate keys and -sign your application .apk files.</li> +sign your application {@code .apk} files.</li> <li>After you sign your application for release, we recommend that you use the <code>zipalign</code> tool to optimize the final APK package.</li> </ul> @@ -82,7 +82,7 @@ run it or debug it on an emulator or device.</p> use to build your application. There are two build modes: <em>debug mode</em> and <em>release mode</em>. You use debug mode when you are developing and testing your application. You use release mode when you want to build a release version of your application that you can -distribute directly to users or publish on an application marketplace such as Android Market.</p> +distribute directly to users or publish on an application marketplace such as Google Play.</p> <p>When you build in <em>debug mode</em> the Android SDK build tools use the Keytool utility (included in the JDK) to create a debug key. Because the SDK build tools created the debug key, @@ -158,10 +158,10 @@ you should ensure that your key's validity period exceeds the expected lifespan of <em>all versions of all of the applications</em>, including dependent applications that may be added to the suite in the future. </li> -<li>If you plan to publish your application(s) on Android Market, the +<li>If you plan to publish your application(s) on Google Play, the key you use to sign the application(s) must have a validity period -ending after 22 October 2033. The Market server enforces this requirement -to ensure that users can seamlessly upgrade Market applications when +ending after 22 October 2033. Google Play enforces this requirement +to ensure that users can seamlessly upgrade applications when new versions are available. </li> </ul> @@ -186,9 +186,9 @@ to the Keytool in the JDK.</p> <p>The Android build tools provide a debug signing mode that makes it easier for you to develop and debug your application, while still meeting the Android system -requirement for signing your .apk. +requirement for signing your APK. When using debug mode to build your app, the SDK tools invoke Keytool to automatically create -a debug keystore and key. This debug key is then used to automatically sign the .apk, so +a debug keystore and key. This debug key is then used to automatically sign the APK, so you do not need to sign the package with your own key.</p> <p>The SDK tools create the debug keystore/key with predetermined names/passwords:</p> @@ -215,19 +215,19 @@ to the public when signed with the debug certificate.</p> <p>If you are developing in Eclipse/ADT (and have set up Keytool and Jarsigner as described above in <a href="#setup">Basic Setup for Signing</a>), signing in debug mode is enabled by default. When you run or debug your -application, ADT signs the .apk with the debug certificate, runs {@code zipalign} on the -package, then installs it on +application, ADT signs the {@code .apk} file with the debug certificate, runs {@code zipalign} on +the package, then installs it on the selected emulator or connected device. No specific action on your part is needed, provided ADT has access to Keytool.</p> <h3>Ant Users</h3> -<p>If you are using Ant to build your .apk files, debug signing mode +<p>If you are using Ant to build your {@code .apk} file, debug signing mode is enabled by using the <code>debug</code> option with the <code>ant</code> command (assuming that you are using a <code>build.xml</code> file generated by the <code>android</code> tool). When you run <code>ant debug</code> to -compile your app, the build script generates a keystore/key and signs the .apk for you. -The script then also aligns the .apk with the <code>zipalign</code> tool. +compile your app, the build script generates a keystore/key and signs the APK for you. +The script then also aligns the APK with the <code>zipalign</code> tool. No other action on your part is needed. Read <a href="{@docRoot}guide/developing/building/building-cmdline.html#DebugMode">Building and Running Apps on the Command Line</a> for more information.</p> @@ -292,7 +292,7 @@ key is one that:</p> with the application</li> <li>Has a validity period that exceeds the expected lifespan of the application or application suite. A validity period of more than 25 years is recommended. -<p>If you plan to publish your application(s) on Android Market, note that a +<p>If you plan to publish your application(s) on Google Play, note that a validity period ending after 22 October 2033 is a requirement. You can not upload an application if it is signed with a key whose validity expires before that date. </p></li> @@ -383,8 +383,8 @@ will use later, to refer to this keystore when signing your application. </p> <p>For more information about Keytool, see the documentation at <a -href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> +href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/keytool.html</a></p> @@ -399,11 +399,11 @@ You can not release your application unsigned, or signed with the debug key.</p> <h4>With Eclipse</h4> -<p>To export an <em>unsigned</em> .apk from Eclipse, right-click the project in the Package +<p>To export an <em>unsigned</em> APK from Eclipse, right-click the project in the Package Explorer and select <strong>Android Tools</strong> > <strong>Export Unsigned Application -Package</strong>. Then specify the file location for the unsigned .apk. -(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, open -the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)</p> +Package</strong>. Then specify the file location for the unsigned APK. +(Alternatively, open your <code>AndroidManifest.xml</code> file in Eclipse, select +the <strong>Manifest</strong> tab, and click <strong>Export an unsigned APK</strong>.)</p> <p>Note that you can combine the compiling and signing steps with the Export Wizard. See <a href="#ExportWizard">Compiling and signing with Eclipse ADT</a>.</p> @@ -414,11 +414,11 @@ the <em>Overview</em> tab, and click <strong>Export an unsigned .apk</strong>.)< with the <code>ant</code> command. For example, if you are running Ant from the directory containing your {@code build.xml} file, the command would look like this:</p> -<pre>ant release</pre> +<pre>$ ant release</pre> -<p>By default, the build script compiles the application .apk without signing it. The output file +<p>By default, the build script compiles the application APK without signing it. The output file in your project {@code bin/} will be <code><em><your_project_name></em>-unsigned.apk</code>. -Because the application .apk is still unsigned, you must manually sign it with your private +Because the application APK is still unsigned, you must manually sign it with your private key and then align it using {@code zipalign}.</p> <p>However, the Ant build script can also perform the signing @@ -443,8 +443,8 @@ machine, as described in <a href="#setup">Basic Setup</a>. Also, make sure that the keystore containing your private key is available.</p> <p>To sign your application, you run Jarsigner, referencing both the -application's .apk and the keystore containing the private key with which to -sign the .apk. The table below shows the options you could use. </p> +application's APK and the keystore containing the private key with which to +sign the APK. The table below shows the options you could use. </p> <table> <tr> @@ -459,6 +459,14 @@ the keystore containing your private key.</td> <td><code>-verbose</code></td><td>Enable verbose output.</td> </tr> <tr> +<td><code>-sigalg</code></td><td>The name of the signature algorithim to use in signing the APK. +Use the value {@code MD5withRSA}.</td> +</tr> +<tr> +<td><code>-digestalg</code></td><td>The message digest algorithim to use in processing the entries +of an APK. Use the value {@code SHA1}.</td> +</tr> +<tr> <td><code>-storepass <password></code></td><td><p>The password for the keystore. </p><p>As a security precaution, do not include this option in your command line unless you are working at a secure computer. @@ -478,19 +486,23 @@ way, your password is not stored in your shell history.</p></td> <code>my_application.apk</code>, using the example keystore created above. </p> -<pre>$ jarsigner -verbose -keystore my-release-key.keystore +<pre>$ jarsigner -verbose -sigalg MD5withRSA -digestalg SHA1 -keystore my-release-key.keystore my_application.apk alias_name</pre> <p>Running the example command above, Jarsigner prompts you to provide -passwords for the keystore and key. It then modifies the .apk -in-place, meaning the .apk is now signed. Note that you can sign an -.apk multiple times with different keys.</p> +passwords for the keystore and key. It then modifies the APK +in-place, meaning the APK is now signed. Note that you can sign an +APK multiple times with different keys.</p> + +<p class="caution"><strong>Caution:</strong> As of JDK 7, the default signing algorithim has +changed, requiring you to specify the signature and digest algorithims ({@code -sigalg} and {@code +-digestalg}) when you sign an APK.</p> -<p>To verify that your .apk is signed, you can use a command like this:</p> +<p>To verify that your APK is signed, you can use a command like this:</p> <pre>$ jarsigner -verify my_signed.apk</pre> -<p>If the .apk is signed properly, Jarsigner prints "jar verified". +<p>If the APK is signed properly, Jarsigner prints "jar verified". If you want more details, you can try one of these commands:</p> <pre>$ jarsigner -verify -verbose my_application.apk</pre> @@ -502,19 +514,19 @@ If you want more details, you can try one of these commands:</p> <p>The command above, with the <code>-certs</code> option added, will show you the "CN=" line that describes who created the key.</p> -<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the .apk was +<p class="note"><strong>Note:</strong> If you see "CN=Android Debug", this means the APK was signed with the debug key generated by the Android SDK. If you intend to release your application, you must sign it with your private key instead of the debug key.</p> <p>For more information about Jarsigner, see the documentation at -<a href="http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security"> -http://java.sun.com/j2se/1.5.0/docs/tooldocs/#security</a></p> +<a href="http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html"> +http://docs.oracle.com/javase/6/docs/technotes/tools/windows/jarsigner.html</a></p> <h3 id="align">4. Align the final APK package</h3> -<p>Once you have signed the .apk with your private key, run <code>zipalign</code> on the file. +<p>Once you have signed the APK with your private key, run <code>zipalign</code> on the file. This tool ensures that all uncompressed data starts with a particular byte alignment, relative to the start of the file. Ensuring alignment at 4-byte boundaries provides a performance optimization when installed on a device. When aligned, the Android @@ -524,16 +536,16 @@ of the data from the package. The benefit is a reduction in the amount of RAM consumed by the running application.</p> <p>The <code>zipalign</code> tool is provided with the Android SDK, inside the -<code>tools/</code> directory. To align your signed .apk, execute:</p> +<code>tools/</code> directory. To align your signed APK, execute:</p> -<pre>zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> +<pre>$ zipalign -v 4 <em>your_project_name</em>-unaligned.apk <em>your_project_name</em>.apk</pre> <p>The {@code -v} flag turns on verbose output (optional). {@code 4} is the byte-alignment (don't use anything other than 4). The first file argument is -your signed .apk (the input) and the second file is the destination .apk file (the output). -If you're overriding an existing .apk, add the {@code -f} flag.</p> +your signed {@code .apk} file (the input) and the second file is the destination {@code .apk} file +(the output). If you're overriding an existing APK, add the {@code -f} flag.</p> -<p class="caution"><strong>Caution:</strong> Your input .apk must be signed with your +<p class="caution"><strong>Caution:</strong> Your input APK must be signed with your private key <strong>before</strong> you optimize the package with {@code zipalign}. If you sign it after using {@code zipalign}, it will undo the alignment.</p> @@ -544,7 +556,7 @@ If you sign it after using {@code zipalign}, it will undo the alignment.</p> <h3 id="ExportWizard">Compile and sign with Eclipse ADT</h3> <p>If you are using Eclipse with the ADT plugin, you can use the Export Wizard to -export a <em>signed</em> .apk (and even create a new keystore, +export a <em>signed</em> APK (and even create a new keystore, if necessary). The Export Wizard performs all the interaction with the Keytool and Jarsigner for you, which allows you to sign the package using a GUI instead of performing the manual procedures to compile, sign, @@ -554,7 +566,7 @@ Because the Export Wizard uses both Keytool and Jarsigner, you should ensure that they are accessible on your computer, as described above in the <a href="#setup">Basic Setup for Signing</a>.</p> -<p>To create a signed and aligned .apk in Eclipse:</p> +<p>To create a signed and aligned APK in Eclipse:</p> <ol> <li>Select the project in the Package @@ -563,7 +575,7 @@ Explorer and select <strong>File > Export</strong>.</li> and click <strong>Next</strong>. <p>The Export Android Application wizard now starts, which will guide you through the process of signing your application, - including steps for selecting the private key with which to sign the .apk + including steps for selecting the private key with which to sign the APK (or creating a new keystore and private key).</p> <li>Complete the Export Wizard and your application will be compiled, signed, aligned, and ready for distribution.</li> diff --git a/docs/html/guide/publishing/licensing.html b/docs/html/guide/publishing/licensing.html new file mode 100644 index 0000000..8e97f32 --- /dev/null +++ b/docs/html/guide/publishing/licensing.html @@ -0,0 +1,11 @@ +<html> +<head> +<meta http-equiv="refresh" +content="0;url=http://developer.android.com/guide/market/licensing/index.html"> +<title>Redirecting...</title> +</head> +<body> +<p>You should have been redirected. Please <a +href="http://developer.android.com/guide/market/licensing/index.html">click here</a>.</p> +</body> +</html>
\ No newline at end of file diff --git a/docs/html/guide/publishing/licensing.jd b/docs/html/guide/publishing/licensing.jd deleted file mode 100644 index 609241b..0000000 --- a/docs/html/guide/publishing/licensing.jd +++ /dev/null @@ -1,2388 +0,0 @@ -page.title=Application Licensing -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Quickview</h2> - <ul> - <li>Licensing lets you protect your application on any device that includes Android Market.</li> - <li>Your app maintains control of how it enforces its licensing status. </li> - <li>Adding licensing to an app is straightforward, using the library available through the SDK.</li> - <li>The service is free and is available to all developers who publish on Android Market. </li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#account">Setting Up A Publisher Account</a></li> - <li><a href="#dev-setup">Setting Up the Development Environment</a></li> - <li><a href="#app-integration">Integrating the LVL with Your Application</a> - <ol> - <li><a href="#add-library">Including the LVL</a></li> - <li><a href="#manifest-permission">Adding the licensing permission</a></li> - <li><a href="#impl-Policy">Implementing a Policy</a></li> - <li><a href="#impl-Obfuscator">Implementing an Obfuscator</a></li> - <li><a href="#impl-lc">Checking the license</a></li> - <li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a></li> - </ol></li> - <li><a href="#test-env">Setting Up the Test Environment</a> - <ol> - <li><a href="#test-response">Test responses</a></li> - <li><a href="#test-acct-setup">Test accounts</a></li> - <li><a href="#acct-signin">Signing in on a device or emulator</a></li> - </ol></li> - <li><a href="#app-obfuscation">Obfuscating Your Application</a></li> - <li><a href="#app-publishing">Publishing a Licensed Application</a></li> - <li><a href="#support">Where to Get Support</a></li> - </ol> - - <h2>Appendix</h2> - <ol> - <li><a href="#lvl-summary">Summary of LVL Classes and Interfaces</a></li> - <li><a href="#server-response-codes">Server Response Codes</a></li> - <li><a href="#extras">Server Response Extras</a></li> - </ol> - -</div> -</div> - -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at run time to -obtain their licensing status for the current user, then allow or disallow -further use as appropriate. </p> - -<p>Using the service, you can apply a flexible licensing policy on an -application-by-application basis — each application can enforce licensing -in the way most appropriate for it. If necessary, an application can apply custom -constraints based on the licensing status obtained from Android Market. -For example, an application can check the licensing status and then apply custom -constraints that allow the user to run it unlicensed for a specific number -of times, or for a specific validity period. An application can also restrict use of the -application to a specific device, in addition to any other constraints. </p> - -<p>The licensing service is a secure means of controlling access to your -applications. When an application checks the licensing status, the Market server -signs the licensing status response using a key pair that is uniquely associated -with the publisher account. Your application stores the public key in its -compiled <code>.apk</code> file and uses it to verify the licensing status -response.</p> - -<p>Any application that you publish through Android Market can use the Android -Market Licensing service. No special account or registration is needed. -Additionally, because the service uses no dedicated framework APIs, you can add -licensing to any legacy application that uses a minimum API level of 3 or -higher.</p> - -<p>To help you add licensing to your application, the Android SDK provides -library sources that you can include in your application project. The -License Verification Library (LVL) handles all of -the licensing-related communication with the Android Market client and the -licensing service. With the LVL integrated, your application can determine its -licensing status for the current user by simply calling a library checker method -and implementing a callback that receives the status.</p> - -<p>This document explains how the licensing service works and how to add it to -your application. </p> - - -<h2 id="overview">Overview</h2> - -<p>Android Market Licensing is a network-based service that lets an application -on an Android-powered device query a trusted licensing server, to determine -whether the application is licensed to the current device user. After receiving -the server response, the application can then allow or disallow further use of -the application as needed. In the service, the role of the licensing server is -to provide the license status for the current user; the application itself is -responsible for querying the server and conditionally granting access to the -application. </p> - -<h4>Application, Android Market client, and server</h4> - -<p>The licensing service is based on the capability of the Android Market server -to determine whether a given user is licensed to use a given application. The licensing server -considers a user to be licensed if the user is a recorded purchaser of an application. If a paid -application has been uploaded to Android Market but saved only as a draft application (in -other words, the app is unpublished), the licensing server considers all users to be licensed users -of the application. Keep in mind, you cannot implement Android Market Licensing in a free -application.</p> - -<p>To properly identify -the user and determine the license status, the server requires information about -the application and user — the application and the Android Market client -work together to assemble the information and pass it to the server. </p> - -<p>In the licensing service, an application does not query the licensing server -directly, but instead calls the Android Market client over remote IPC to -initiate a license request. In the license request:</p> - -<ul> -<li>The application provides its package name and a nonce that is later used to -validate any response from the server, as well as a callback over which the -response can be returned asynchronously.</li> -<li>The Android Market client, which has greater permissions than the -application, collects the necessary information about the user and the device, -such as the device's primary Google account username, IMSI, and other -information. It then sends the license check request to the server on behalf of -the application.</li> -<li>The server evaluates the request using all available information, attempting -to establish the user's identity to a sufficient level of confidence. The server -then checks the user identity against purchase records for the application and -returns a license response, which the Android Market client returns to the -application over the IPC callback.</li> -</ul> - -<p>Notice that during a license check, the application does not manage any -network connections or use any licensing related APIs in the Android platform. -</p> - -<div class="figure" style="width:469px"> -<img src="{@docRoot}images/licensing_arch.png" alt=""/> -<p class="img-caption"><strong>Figure 1.</strong> Your application initiates a -license check through the LVL and the Android Market -client, which handles communication with the Market server.</p> -</div> - -<h4>License responses secured through public key cryptography</h4> - -<p>To ensure the integrity of each license query, the server signs the license -response data using an RSA key pair that is shared exclusively between the -server and the application publisher.</p> - -<p>The licensing service generates a single licensing key pair for each -publisher account and exposes the public key in the account's profile page. The -publisher copies the public key and embeds it in the application source code, -then compiles and publishes the <code>.apk.</code> The server retains the -private key internally and uses it to sign license responses for applications -published on that account. </p> - -<p>When the application receives a signed response, it uses the embedded public -key to verify the data. The use of public key cryptography in the licensing -service makes it possible for the application to detect responses that have been -tampered with or that are spoofed.</p> - -<h4>Use of licensing in your application</h4> - -<p>To use licensing in your application, add code to the application to -initiate a license check request and handle the response when it is received. -You can choose when, and how often, you want your application to check its -license and you have full control over how it handles the response, verifies the -signed response data, and enforces access controls. </p> - -<p>To simplify the process of adding support for licensing, download and -integrate the Licensing Verification Library, described below. Integration is -straightforward.</p> - -<p>When you are finished integrating the LVL, use a test environment -provided by the publisher site to test your application's handling of server -responses. </p> - -<p>Finally, publish the application <code>.apk</code> on Market using the -normal process. If you previously used the copy-protection provided by Android -Market, you can remove it from applications that use licensing. </p> - -<h4>Licensing Verification Library simplifies implementation</h4> - -<p>The Android SDK includes a License Verification Library (LVL) that you can -download and use as the basis for your application's licensing implementation. -The LVL greatly simplifies the process of adding licensing to your application -and helps ensure a more secure, robust implementation for your application. The -LVL provides internal classes that handle most of the standard operations of a -license query, such as contacting Android Market to initiate a license request -and verifying and validating the responses. It also exposes key interfaces that -let you easily plug in your custom code for defining licensing policy and -managing access as needed by your application. The key LVL interfaces are: </p> - -<ul> -<li>Policy — your implementation determines whether to allow access to the -application, based on the license response received from the server and any -other data available (such as from a backend server associated with your -application). The implementation can evaluate the various fields of the license -response and apply other constraints, if needed. The implementation also lets -you manage the handling of license checks that result in errors, such as network -errors.</li> -<li>LicenseCheckerCallback — your implementation manages access to the -application, based on the result of the Policy's handling of the license -response. Your implementation can manage access in any way needed, including -displaying the license result in the UI or directing the user to purchase the -application (if not currently licensed). </li> -</ul> - -<p>To help you get started with a Policy, the LVL provides two fully complete -Policy implementations that you can use without modification or adapt to your -needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a> is a flexible Policy -that uses settings provided by the licensing server to manage response caching -and access to the application while the device is offline (such as when the -user is on an airplane). For most applications, the use of -ServerManagedPolicy is highly recommended. </li> -<li><a href="#StrictPolicy">StrictPolicy</a> is a restrictive Policy that -does not cache any response data and allows the application access <em>only</em> -when the server returns a licensed response.</li> -</ul> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes both the LVL itself and an example application that shows how -the library should be integrated with your application and how your application -should manage response data, UI interaction, and error conditions. </p> - -<p>The LVL sources are provided as an Android <em>library project</em>, which -means that you can maintain a single set of library sources and share them -across multiple applications. A full test environment is also available through -the SDK, so you can develop and test the licensing implementation in your -applications before publishing them, even if you don't have access to a -physical device.</p> - -<h4>Requirements and limitations</h4> - -<p>Android Market Licensing is designed to let you apply license controls to -applications that you publish through Android Market. The service is not -designed to let you control access to applications that are not published -through Android Market or that are run on devices that do not offer the Android -Market client. </p> - -<p>Here are some points to keep in mind as you implement licensing in your -application: </p> - -<ul> -<li>Only paid applications published through Market can use the -service.</li> -<li>An application can use the service only if the Android Market client is -installed on its host device and the device is running Android 1.5 (API level 3) -or higher.</li> -<li>To complete a license check, the licensing server must be accessible over -the network. You can implement license caching behaviors to manage access when -there is no network connectivity. </li> -<li>The security of your application's licensing controls ultimately relies on -the design of your implementation itself. The service provides the building -blocks that let you securely check licensing, but the actual enforcement and -handling of the license are factors in your control. By following the best -practices in this document, you can help ensure that your implementation will be -secure.</li> -<li>Adding licensing to an application does not affect the way the application -functions when run on a device that does not offer Android Market.</li> -<li>Licensing is currently for paid apps only, since draft apps are -licensed for all users. If your application is already published as a free app, -you won't be able to upload a new version that uses licensing.</li> -</ul> - -<h4>Replacement for Copy Protection</h4> - -<p>Android Market Licensing is a flexible, secure mechanism for controlling -access to your applications. It effectively replaces the Copy Protection -mechanism offered on Android Market and gives you wider distribution -potential for your applications. </p> - -<ul> -<li>A limitation of the legacy Copy Protection mechanism on Android Market is -that applications using it can be installed only on compatible devices that -provide a secure internal storage environment. For example, a copy-protected -application cannot be downloaded from Market to a device that provides root -access, and the application cannot be installed to a device's SD card. </li> -<li>With Android Market licensing, you can move to a license-based model in -which access is not bound to the characteristics of the host device, but to your -publisher account on Android Market and the licensing policy that you define. -Your application can be installed and controlled on any compatible device on -any storage, including SD card.</li> -</ul> - -<p>Although no license mechanism can completely prevent all unauthorized use, -the licensing service lets you control access for most types of normal usage, -across all compatible devices, locked or unlocked, that run Android 1.5 or -higher version of the platform.</p> - -<p>The sections below describe how to add Android Market licensing to your -applications. </p> - -<h2 id="account">Setting Up a Publisher Account</h2> - -<p>Android Market licensing lets you manage access to applications that -users have downloaded from Android Market. To use licensing in an application, -you need to have a publisher account on Android Market so that you can -publish the application to users. </p> - -<p>If you don't already have a publisher account, you need to register for one -using your Google account and agree to the terms of service. Once you are -registered, you can upload applications at your convenience and begin debugging -and testing your licensing implementation. For more information about publishing -on Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html">Publishing Your -Applications</a></p> - -<p>To register as an Android Market developer and set up your publisher account, -visit the Android Market publisher site:</p> - -<p style="margin-left:2em;"><a -href="http://market.android.com/publish">http://market.android.com/publish</a> -</p> - -<p>If you already have a publisher account on Android Market, use your existing -account to set up licensing. You <em>do not</em> need to register for a new -account to support licensing (and doing so is not recommended, especially if you -are adding licensing support to applications that you have already published). -In all cases, if you have published applications, you manage licensing for those -applications through the account on which the applications are published. </p> - -<p>Once your publisher account is set up, use the account to:</p> - -<ul> -<li>Obtain a public key for licensing</li> -<li>Debug and test an application's licensing implementation, prior to -publishing the application</li> -<li>Publish the applications to which you have added licensing support</li> -</ul> - -<h4>Administrative settings for licensing</h4> - -<p>Once you are signed into your publisher account, you can manage several -administrative controls for Android Market licensing. The controls are available -in the Edit Profile page, in the "Licensing" panel, shown below. The controls -let you: </p> - -<ul> -<li>Set up multiple "test accounts", identified by email address. The licensing -server allows users signed into test accounts on a device or emulator to send -license checks and receive static test responses.</li> -<li>Obtain the account's public key for licensing. When you are implementing -licensing in an application, you must copy the public key string into the -application.</li> -<li>Configure static test responses that the server sends, when it receives a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_public_key.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 2.</strong> The Licensing -panel of your account's Edit Profile page lets you manage administrative -settings for licensing.</div> -</div> - -<p>For more information about how to work with test accounts and static test -responses, see <a href="#test-env">Setting Up a Testing Environment</a>, below. - -<h2 id="dev-setup">Setting Up the Development Environment</h2> - -<p>Once you've set up your publisher account on Android Market, the next step is -to set up your development environment for licensing. </p> - -<p>Setting up your environment for licensing involves these tasks:</p> - -<ol> -<li><a href="#download-sdk">Downloading the latest SDK</a>, if you haven't already done so </li> -<li><a href="#runtime-setup">Setting up the runtime environment</a> for development</li> -<li><a href="#download-lvl">Downloading the Market Licensing component</a> into your SDK </li> -<li><a href="#lvl-setup">Setting up the Licensing Verification Library</a></li> -<li><a href="#add-library">Including the LVL library project in your application</a></li> -</ol> - -<p>The sections below describe these tasks. When you are done with setup, -you can begin <a href="#app-integration">integrating the LVL into your applications</a>.</p> - -<p>To get started, you need to set up a proper runtime environment on which -you can run, debug and test your application's implementation of license -checking and enforcement. </p> - - -<h3 id="download-sdk">Downloading the latest SDK</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Licensing sample application</h2> - -<p>To work with Android Market licensing, you need a functioning Android -application to which you can add licensing support. </p> - -<p style="margin-top:.5em;">If you are new to Android -and don't yet have a functioning application, the LVL component includes a sample -application that you can set up as a new application project. The sample provides -a complete, working example of how licensing works. For more information, see <a -href="#download-lvl">Downloading the LVL</a>.</p> - -</div> -</div> - -<p>If you haven't done so, you need to download the Android SDK before you can -develop Android applications. The SDK provides the tools that you need to build -and debug Android applications, including applications that use Android Market -licensing. For complete information, including installation instructions, see -the <a href="{@docRoot}sdk/index.html">Android SDK</a>. </p> - -<p>If you have already installed the SDK, make sure to update the -SDK tools and ADT Plugin to the latest versions. You can update the SDK tools -using the Android SDK and AVD Manager and ADT through <strong>Help</strong> > -<strong>Software Updates...</strong> in Eclipse. </p> - -<p>After you've installed the latest SDK and tools, set up your development -environment as described below. </p> - - -<h3 id="runtime-setup">Setting up the runtime environment</h3> - -<p>As described earlier, applications check licensing status not by contacting -the licensing server directly, but by binding to a service provided by the -Android Market application and initiating a license check request. The Android -Market service then handles the direct communication with the licensing server -and finally routes the response back to your application. To debug and test -licensing in your application, you need to set up a runtime environment that -includes the necessary Android Market service, so that your application is able -to send license check requests to the licensing server. </p> - -<p>There are two types of runtime environment that you can use: </p> - -<ul> -<li>An Android-powered device that includes the Android Market application, or</li> -<li>An Android emulator running the Google APIs Add-on, API level 8 (release 2) -or higher</li> -</ul> - -<p>The sections below provide more information. </p> - -<h4 id="runtime-device">Running on a device</h4> - -<p>You can use an Android-powered device as the runtime environment for -debugging and testing licensing on your application.</p> - -<p>The device you use must:</p> - -<ul> -<li>Run a standard version of the Android 1.5 or later (API level -3 or higher) platform, <em>and</em> </li> -<li>Run a system image on which the Android Market client application -is preinstalled. </li> -</ul> - -<p>If Android Market is not preinstalled in the system image, your application won't -be able to communicate with the Android Market licensing server. </p> - -<p>For general information about how to set up a device for use in developing -Android applications, see <a -href="{@docRoot}guide/developing/device.html">Developing on a Device</a>.</p> - -<h4 id="runtime-emulator">Running on an Android emulator</h4> - -<p>You can also use an Android emulator as your runtime -environment for debugging and testing licensing.</p> - -<p>Because the standard Android platforms provided in the Android SDK <em>do -not</em> include Android Market, you need to download the Google APIs Add-On -platform, API Level 8 (or higher), from the SDK repository. After downloading -the add-on, you need to create an AVD configuration that uses that system image. -</p> - -<p>The Google APIs Add-On does not include the full Android Market client. -However, it does provide: </p> - -<ul> -<li>An Android Market background service that implements the -ILicensingService remote interface, so that your application can -send license checks over the network to the licensing server. </li> -<li>A set of underlying account services that let you add an a Google account on -the AVD and sign in using your publisher account or test account credentials. -Signing in using your publisher or test account enables you to debug and test -your application without having publish it. For more information see <a -href="#acct-signin">Signing in to an authorized account</a>, below.</li> -</ul> - -<p>Several versions of the add-on are available in the SDK repository, but only -<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> version of the -add-on includes the necessary Android Market services. This means that you -cannot use Google APIs Add-On API 7 or lower as a runtime environment for -developing licensing on an emulator.</p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_gapis_8.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 3.</strong> Google APIs -Add-On, API 8 (release 2) or higher lets you debug and test your licensing -implementation in an emulator.</div> -</div> - -<p>To set up an emulator for adding licensing to an application, follow -these steps: </p> - -<ol> - <li>Launch the Android SDK and AVD Manager. </li> - <li>In the <strong>Available Packages</strong> panel, select and download the -SDK component "Google APIs (Google Inc.) - API Level 8" (or higher) from the SDK -repository, as shown in the figure above. - <p>When the download is complete, use the Android SDK and AVD Manager to -create a new AVD based on that component, described next.</p></li> - <li>In the <strong>Virtual -Devices</strong> panel of the Android SDK and AVD Manager, click -<strong>New</strong> and set the configuration details for the new AVD. </li> - <li>In the dialog that appears, assign a descriptive name to the AVD and then -use the "Target" menu to choose the "Google APIs (Google Inc.) - API Level 8" as -the system image to run on the new AVD. Set the other configuration details as -needed and then click <strong>Create AVD</strong> to finish. The SDK tools -create the new AVD configuration, which then appears in the list of available -Android Virtual Devices.</li> -</ol> - -<p>If you are not familiar with AVDs or how to use them, see <a -href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a>.</p> - -<h4 id="project-update">Updating your project configuration</h4> - -<p>After you set up a runtime environment that meets the requirements described -above — either on an actual device or on an emulator — make sure to -update your application project or build scripts as needed, so that your compiled -<code>.apk</code> files that use licensing are deployed into that environment. -In particular, if you are developing in Eclipse, make sure that you set up a -Run/Debug Configuration that targets the appropriate device or AVD. </p> - -<p>You do not need to make any changes to your application's -build configuration, provided that the project is already configured to compile -against a standard Android 1.5 (API level 3) or higher library. For example: - -<ul> -<li>If you have an existing application that is compiled against -the Android 1.5 library, you do not need to make any changes to your -build configuration to support licensing. The build target meets the minimum -requirements for licensing, so you would continue building -against the same version of the Android platform.</li> - -<li>Similarly, if you are building against Android 1.5 (API level 3) but -are using an emulator running the Google APIs Add-On API 8 as the application's -runtime environment, there is no need to change your application's build -configuration. </li> -</ul> - -<p>In general, adding licensing to an application should have no impact -whatsoever on the application's build configuration.</p> - - -<h3 id="download-lvl">Downloading the LVL</h3> - -<p>The License Verification Library (LVL) is a collection of helper classes that -greatly simplify the work that you need to do to add licensing to your -application. In all cases, we recommend that you download the LVL and use it as -the basis for the licensing implementation in your application.</p> - -<p>The LVL is available as a downloadable component of the Android SDK. The -component includes: </p> - -<ul> -<li>The LVL sources, stored inside an Android library project. </li> -<li>An example application called "sample" that depends on the LVL library -project. The example illustrates how an application uses the library helper -classes to check and enforce licensing.</li> -</ul> - -<p>To download the LVL component into your development environment, use the -Android SDK and AVD Manager. Launch the Android SDK and AVD Manager and then -select the "Market Licensing" component, as shown in the figure below. -Accept the terms and click <strong>Install Selected</strong> to begin the download. </p> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_package.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 4.</strong> The Market -Licensing package contains the LVL and the LVL sample application. </div> -</div> - -<p>When the download is complete, the Android SDK and AVD Manager installs both -the LVL library project and the example application into these directories: </p> - -<p style="margin-left:2em"><code><<em>sdk</em>>/extras/google/market_licensing/library/</code> - (the LVL library project)<br /> -<code><<em>sdk</em>>/extras/google/market_licensing/sample/</code> (the example -application)</p> - -<p>If you aren't familiar with how to download components into your SDK, see the -<a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> -document. </p> - - -<h3 id="lvl-setup">Setting Up the Licensing Verification Library</h3> - -<p>After downloading the LVL to your computer, you need to set it up in your -development environment, either as an Android library project or by -copying (or importing) the library sources directly into your existing -application package. In general, using the LVL as a library project is recommended, -since it lets you reuse your licensing code across multiple applications and -maintain it more easily over time. Note that the LVL is not designed to be -compiled separately and added to an application as a static .jar file. </p> - -<h4>Moving the library sources to a new location</h4> - -<p>Because you will be customizing the LVL sources to some extent, you should -make sure to <em>move or copy</em> the library sources (the entire -directory at <code><<em>sdk</em>>/market_licensing/library/</code>) -to a working directory outside of the SDK. You should then use the relocated -sources as your working set. If you are using a source-code management -system, add and track the sources that are in the working location rather -than those in default location in the SDK. </p> - -<p>Moving the library sources is important is because, when you later update the -Market licensing package, the SDK installs the new files to the same location as -the older files. Moving your working library files to a safe location ensures -that your work won't be inadvertently overwritten should you download a new -version of the LVL.</p> - -<h4>Creating the LVL as a library project</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Working with library projects</h2> - -<p>The LVL is provided as an Android library project, which means that you can -share its code and resources across multiple applications. </p> - -<p style="margin-top:.5em;">If you aren't familiar with library projects or how -to use them, see <a href="{@docRoot}guide/developing/projects/index.html#LibraryProjects"> -Managing Projects</a>. -</p> -</div> -</div> - -<p>The recommended way of using the LVL is setting it up as a new Android -<em>library project</em>. A library project is a type of development project -that holds shared Android source code and resources. Other Android application -projects can reference the library project and, at build time, include its -compiled sources in their <code>.apk</code> files. In the context of licensing, -this means that you can do most of your licensing development once, in a library -project, then include the library sources in your various application projects. -In this way, you can easily maintain a uniform implementation of licensing -across all of your projects and maintain it centrally. </p> - -<p>The LVL is provided as a configured library project — once you have -downloaded it, you can start using it right away. </p> - -<p>If you are working in Eclipse with ADT, you need to add the LVL to your -workspace as a new development project, in the same way as you would a new -application project. </p> - -<ol> -<li>Use the New Project Wizard to create a new -project from existing sources. Select the LVL's <code>library</code> directory -(the directory containing the library's AndroidManifest.xml file) as the project -root.</li> -<li>When you are creating the library project, you can select any application -name, package, and set other fields as needed. </li> -<li>For the library's build target, select Android 1.5 (API level 3) or higher.</li> -</ol> - -<p> When created, the project is -predefined as a library project in its <code>project.properties</code> file, so -no further configuration is needed. </p> - -<p>For more information about how to create an application project or work with -library projects in Eclipse, see <a -href="{@docRoot}guide/developing/projects/projects-eclipse.html">Managing Projects from -Eclipse with ADT</a></p>. - -<h4>Copying the LVL sources to your application</h4> - -<p>As an alternative to adding the LVL as a library project, you can copy the -library sources directly into your application. To do so, copy (or import) the -LVL's <code>library/src/com</code> directory into your application's -<code>src/</code> directory.</p> - -<p>If you add the LVL sources directly to your application, you can skip the -next section and start working with the library, as described in <a -href="#app-integration"></a>.</p> - - -<h3 id="add-library">Including the LVL library project sources in your -application</h3> - -<p>If you want to use the LVL sources as a library project, you need to add a -reference to the LVL library project in your application project properties. This tells -build tools to include the LVL library project sources in your application at -compile time. The process for adding a reference to a library project depends -on your development environment, as described below.</p> - -<p> If you are developing in Eclipse with ADT, you should already have added the -library project to your workspace, as described in the previous section. If you -haven't done that already, do it now before continuing. </p> - -<p>Next, open the application's project properties window, as shown below. -Select the "Android" properties group and click <strong>Add</strong>, then -choose the LVL library project (com_android_vending_licensing) and click -<strong>OK</strong>. For more information, see -<a href="{@docRoot}guide/developing/projects/projects-eclipse.html#SettingUpLibraryProject"> -Managing Projects from Eclipse with ADT</a></p>. - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_add_library.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 5.</strong> If you are -working in Eclipse with ADT, you can add the LVL library project to your -application from the application's project properties.</div> -</div> - -<p>If you are developing using the SDK command-line tools, navigate to the -directory containing your application project and open the -<code>project.properties</code> file. Add a line to the file that specifies the -<code>android.library.reference.<n></code> key and the path to the -library. For example: </p> - -<pre>android.library.reference.1=path/to/library_project</pre> - -<p>Alternatively, you can use this command to update the project -properties, including the reference to the library project:</p> - -<pre class="no-pretty-print" style="color:black">android update lib-project ---target <em><target_ID></em> \ ---path <em>path/to/my/app_project</em> \ ---library <em>path/to/my/library_project</em> -</pre> - -<p>For more information about working with library projects, -see <a href="{@docRoot}guide/developing/projects/projects-cmdline.html#SettingUpLibraryProject"> -Managing Projects from the Command Line</a></p>. - - -<h2 id="app-integration">Integrating the LVL with Your Application</h2> - -<p>Once you've followed the steps above to set up a publisher account and -development environment, you are ready to begin integrating the LVL with your -application. </p> - -<p>Integrating the LVL with your application code involves these tasks:</p> - -<ol> -<li><a href="#manifest-permission">Adding the licensing permission</a> your application's manifest.</li> -<li><a href="#impl-Policy">Implementing a Policy</a> — you can choose one of the full implementations provided in the LVL or create your own.</li> -<li><a href="#impl-Obfuscator">Implementing an Obfuscator</a>, if your Policy will cache any license response data. </li> -<li><a href="#impl-lc">Adding code to check the license</a> in your application's main Activity</li> -<li><a href="#impl-DeviceLimiter">Implementing a DeviceLimiter</a> (optional and not recommended for most applications)</li> -</ol> - -<p>The sections below describe these tasks. When you are done with the -integration, you should be able to compile your application successfully and you -can begin testing, as described in <a href="#test-env">Setting Up the Test -Environment</a>.</p> - -<p>For an overview of the full set of source files included in the LVL, see <a -href="#lvl-summary">Summary of LVL Classes and Interfaces</a>.</p> - - -<h3 id="manifest-permission">Adding the licensing permission to your -AndroidManifest.xml</h3> - -<p>To use the Android Market application for sending a license check to the -server, your application must request the proper permission, -<code>com.android.vending.CHECK_LICENSE</code>. If your application does -not declare the licensing permission but attempts to initiate a license check, -the LVL throws a security exception.</p> - -<p>To request the licensing permission in your application, declare a <a -href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a> -element as a child of <code><manifest></code>, as follows: </p> - -<p style="margin-left:2em;"><code><uses-permission -android:name="com.android.vending.CHECK_LICENSE"></code></p> - -<p>For example, here's how the LVL sample application declares the permission: -</p> - -<pre><?xml version="1.0" encoding="utf-8"?> - -<manifest xmlns:android="http://schemas.android.com/apk/res/android" ..."> - <!-- Devices >= 3 have version of Android Market that supports licensing. --> - <uses-sdk android:minSdkVersion="3" /> - <!-- Required permission to check licensing. --> - <uses-permission android:name="com.android.vending.CHECK_LICENSE" /> - ... -</manifest> -</pre> - -<p class="note"><strong>Note:</strong> Currently, you cannot declare the -<code>CHECK_LICENSE</code> permission in the LVL library project's manifest, -because the SDK Tools will not merge it into the manifests of dependent -applications. Instead, you must declare the permission in each dependent -application's manifest. </p> - - -<h3 id="impl-Policy">Implementing a Policy</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>ServerManagedPolicy</h2> - -<p>The LVL includes a complete Policy implementation called ServerManagedPolicy -that makes use of license-management settings provided by the Android Market -server. </p> - -<p style="margin-top:.5em;">Use of ServerManagedPolicy as the basis for your -Policy is strongly recommended. For more information, see <a -href="#ServerManagedPolicy">ServerManagedPolicy</a> section, below.</p> - -</div> -</div> - -<p>Android Market licensing service does not itself determine whether a -given user with a given license should be granted access to your application. -Rather, that responsibility is left to a Policy implementation that you provide -in your application.</p> - -<p>Policy is an interface declared by the LVL that is designed to hold your -application's logic for allowing or disallowing user access, based on the result -of a license check. To use the LVL, your application <em>must</em> provide an -implementation of Policy. </p> - -<p>The Policy interface declares two methods, <code>allowAccess()</code> and -<code>processServerResponse()</code>, which are called by a LicenseChecker -instance when processing a response from the license server. It also declares an -enum called <code>LicenseResponse</code>, which specifies the license response -value passed in calls to <code>processServerResponse()</code>. </p> - -<ul> -<li><code>processServerResponse()</code> lets you preprocess the raw response -data received from the licensing server, prior to determining whether to grant -access. - -<p>A typical implementation would extract some or all fields from the license -response and store the data locally to a persistent store, such as through -{@link android.content.SharedPreferences} storage, to ensure that the data is -accessible across application invocations and device power cycles. For example, -a Policy would maintain the timestamp of last successful license check, the -retry count, the license validity period, and similar information in a -persistent store, rather than resetting the values each time the application is -launched.</p> - -<p>When storing response data locally, the Policy must ensure that the data is -obfuscated (see <a href="#impl-Obfuscator">Implementing an Obfuscator</a>, -below).</p></li> - -<li><code>allowAccess()</code> determines whether to grant the user access to -your application, based on any available license response data (from the -licensing server or from cache) or other application-specific information. For -example, your implementation of <code>allowAccess()</code> could take into -account additional criteria, such as usage or other data retrieved from a -backend server. In all cases, an implementation of <code>allowAccess()</code> -should only return <code>true</code> if the user is licensed to use the -application, as determined by the licensing server, or if there is a transient -network or system problem that prevents the license check from completing. In -such cases, your implementation can maintain a count of retry responses and -provisionally allow access until the next license check is complete.</li> - -</ul> - -<p>To simplify the process of adding licensing to your application and to -provide an illustration of how a Policy should be designed, the LVL includes -two full Policy implementations that you can use without modification or -adapt to your needs:</p> - -<ul> -<li><a href="#ServerManagedPolicy">ServerManagedPolicy</a>, a flexible Policy -that uses server-provided settings and cached responses to manage access across -varied network conditions, and</li> -<li><a href="#StrictPolicy">StrictPolicy</a>, which does not cache any response -data and allows access <em>only</em> if the server returns a licensed -response.</li> -</ul> - -<p>For most applications, the use of ServerManagedPolicy is highly -recommended. ServerManagedPolicy is the LVL default and is integrated with -the LVL sample application.</p> - - -<h4 id="custom-policies">Guidelines for custom policies</h4> - -<p>In your licensing implementation, you can use one of the complete policies -provided in the LVL (ServerManagedPolicy or StrictPolicy) or you can create a -custom policy. For any type of custom policy, there are several important design -points to understand and account for in your implementation.</p> - -<p>The licensing server applies general request limits to guard against overuse -of resources that could result in denial of service. When an application exceeds -the request limit, the licensing server returns a 503 response, which gets -passed through to your application as a general server error. This means that no -license response will be available to the user until the limit is reset, which -can affect the user for an indefinite period.</p> - -<p>If you are designing a custom policy, we recommend that the Policy: -<ol> -<!-- <li>Limits the number of points at which your app calls for a license check -to the minimum. </li> --> -<li>Caches (and properly obfuscates) the most recent successful license response -in local persistent storage.</li> -<li>Returns the cached response for all license checks, for as long as the -cached response is valid, rather than making a request to the licensing server. -Setting the response validity according to the server-provided <code>VT</code> -extra is highly recommended. See <a href="#extras">Server Response Extras</a> -for more information.</li> -<li>Uses an exponential backoff period, if retrying any requests the result in -errors. Note that the Android Market client automatically retries failed -requests, so in most cases there is no need for your Policy to retry them.</li> -<li>Provides for a "grace period" that allows the user to access your -application for a limited time or number of uses, while a license check is being -retried. The grace period benefits the user by allowing access until the next -license check can be completed successfully and it benefits you by placing a -hard limit on access to your application when there is no valid license response -available.</li> -</ol> - -<p>Designing your Policy according to the guidelines listed above is critical, -because it ensures the best possible experience for users while giving you -effective control over your application even in error conditions. </p> - -<p>Note that any Policy can use settings provided by the licensing server to -help manage validity and caching, retry grace period, and more. Extracting the -server-provided settings is straightforward and making use of them is highly -recommended. See the ServerManagedPolicy implementation for an example of how to -extract and use the extras. For a list of server settings and information about -how to use them, see <a href="#extras">Server Response Extras</a> in the -Appendix of this document.</p> - -<h4 id="ServerManagedPolicy">ServerManagedPolicy</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Server Response Extras</h2> - -<p>For certain types of licensing responses, the licensing server appends extra -settings to the responses, to help the application manage licensing effectively. -</p> - -<p style="margin-top:.5em;">See <a href="#extras">Server Response Extras</a> for -a list of settings and <code>ServerManagedPolicy.java</code> for information -about how a Policy can use the extras.</p> - -</div> -</div> - -<p>The LVL includes a full and recommended implementation of the Policy -interface called ServerManagedPolicy. The implementation is integrated with the -LVL classes and serves as the default Policy in the library. </p> - -<p>ServerManagedPolicy provides all of the handling for license and retry -responses. It caches all of the response data locally in a -{@link android.content.SharedPreferences} file, obfuscating it with the -application's Obfuscator implementation. This ensures that the license response -data is secure and persists across device power cycles. ServerManagedPolicy -provides concrete implementations of the interface methods -<code>processServerResponse()</code> and <code>allowAccess()</code> and also -includes a set of supporting methods and types for managing license -responses.</p> - -<p>Importantly, a key feature of ServerMangedPolicy is its use of -server-provided settings as the basis for managing licensing across an -application's refund period and through varying network and error conditions. -When an application contacts the Android Market server for a license check, the -server appends several settings as key-value pairs in the extras field of certain -license response types. For example, the server provides recommended values for the -application's license validity period, retry grace period, and maximum allowable -retry count, among others. ServerManagedPolicy extracts the values from the -license response in its <code>processServerResponse()</code> method and checks -them in its <code>allowAccess()</code> method. For a list of the server-provided -settings used by ServerManagedPolicy, see <a href="#extras">Server Response -Extras</a> in the Appendix of this document.</p> - -<p>For convenience, best performance, and the benefit of using license settings -from the Android Market server, <strong>using ServerManagedPolicy as your -licensing Policy is strongly recommended</strong>. </p> - -<p>If you are concerned about the security of license response data that is -stored locally in SharedPreferences, you can use a stronger obfuscation -algorithm or design a stricter Policy that does not store license data. The LVL -includes an example of such a Policy — see <a -href="#StrictPolicy">StrictPolicy</a> for more information.</p> - -<p>To use ServerManagedPolicy, simply import it to your Activity, create an -instance, and pass a reference to the instance when constructing your -LicenseChecker. See <a href="#lc-lcc">Instantiate LicenseChecker and -LicenseCheckerCallback</a> for more information. </p> - -<h4 id="StrictPolicy">StrictPolicy</h4> - -<p>The LVL includes an alternative full implementation of the Policy interface -called StrictPolicy. The StrictPolicy implementation provides a more restrictive -Policy than ServerManagedPolicy, in that it does not allow the user to access -the application unless a license response is received from the server at the -time of access that indicates that the user is licensed.</p> - -<p>The principal feature of StrictPolicy is that it does not store <em>any</em> -license response data locally, in a persistent store. Because no data is stored, -retry requests are not tracked and cached responses can not be used to fulfill -license checks. The Policy allows access only if:</p> - -<ul> -<li>The license response is received from the licensing server, and </li> -<li>The license response indicates that the user is licensed to access the -application. </li> -</ul> - -<p>Using StrictPolicy is appropriate if your primary concern is to ensure that, -in all possible cases, no user will be allowed to access the application unless -the user is confirmed to be licensed at the time of use. Additionally, the -Policy offers slightly more security than ServerManagedPolicy — since -there is no data cached locally, there is no way a malicious user could tamper -with the cached data and obtain access to the application.</p> - -<p>At the same time, this Policy presents a challenge for normal users, since it -means that they won't be able to access the application when there is no network -(cell or wi-fi) connection available. Another side-effect is that your -application will send more license check requests to the server, since using a -cached response is not possible.</p> - -<p>Overall, this policy represents a tradeoff of some degree of user convenience -for absolute security and control over access. Consider the tradeoff carefully -before using this Policy.</p> - -<p>To use StrictPolicy, simply import it to your Activity, create an instance, -and pass a reference to it when constructing your LicenseChecker. See -<a href="#lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</a> -for more information. </p> - -<h3 id="impl-Obfuscator">Implementing an Obfuscator</h3> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>AESObfuscator</h2> - -<p>The LVL includes a full Obfuscator implementation in the -<code>AESObfuscator.java</code> file. The Obfuscator uses AES encryption to -obfuscate/unobfuscate data. If you are using a Policy (such as -ServerManagedPolicy) that caches license response data, using AESObfuscator as -basis for your Obfuscator implementation is highly recommended. </p> - -</div> -</div> - -<p>A typical Policy implementation needs to save the license response data for -an application to a persistent store, so that it is accessible across -application invocations and device power cycles. For example, a Policy would -maintain the timestamp of the last successful license check, the retry count, -the license validity period, and similar information in a persistent store, -rather than resetting the values each time the application is launched. The -default Policy included in the LVL, ServerManagedPolicy, stores license response -data in a {@link android.content.SharedPreferences} instance, to ensure that the -data is persistent. </p> - -<p>Because the Policy will use stored license response data to determine whether -to allow or disallow access to the application, it <em>must</em> ensure that any -stored data is secure and cannot be reused or manipulated by a root user on a -device. Specifically, the Policy must always obfuscate the data before storing -it, using a key that is unique for the application and device. Obfuscating using -a key that is both application-specific and device-specific is critical, because -it prevents the obfuscated data from being shared among applications and -devices.</p> - -<p>The LVL assists the application with storing its license response data in a -secure, persistent manner. First, it provides an Obfuscator -interface that lets your application supply the obfuscation algorithm of its -choice for stored data. Building on that, the LVL provides the helper class -PreferenceObfuscator, which handles most of the work of calling the -application's Obfuscator class and reading and writing the obfuscated data in a -SharedPreferences instance. </p> - -<p>The LVL provides a full Obfuscator implementation called -AESObfuscator that uses AES encryption to obfuscate data. You can -use AESObfuscator in your application without modification or you -can adapt it to your needs. For more information, see the next section.</p> - - -<h4 id="AESObfuscator">AESObfuscator</h4> - -<p>The LVL includes a full and recommended implementation of the Obfuscator -interface called AESObfuscator. The implementation is integrated with the -LVL sample application and serves as the default Obfuscator in the library. </p> - -<p>AESObfuscator provides secure obfuscation of data by using AES to -encrypt and decrypt the data as it is written to or read from storage. -The Obfuscator seeds the encryption using three data fields provided -by the application: </p> - -<ol> -<li>A salt — an array of random bytes to use for each (un)obfuscation. </li> -<li>An application identifier string, typically the package name of the application.</li> -<li>A device identifier string, derived from as many device-specific sources -as possible, so as to make it as unique.</li> -</ol> - -<p>To use AESObfuscator, first import it to your Activity. Declare a private -static final array to hold the salt bytes and initialize it to 20 randomly -generated bytes.</p> - -<pre> ... - // Generate 20 random bytes, and put them here. - private static final byte[] SALT = new byte[] { - -46, 65, 30, -128, -103, -57, 74, -64, 51, 88, -95, - -45, 77, -117, -36, -113, -11, 32, -64, 89 - }; - ... -</pre> - -<p>Next, declare a variable to hold a device identifier and generate a value for -it in any way needed. For example, the sample application included in the LVL -queries the system settings for the -<code>android.Settings.Secure.ANDROID_ID</code>, which is unique to each device. -</p> - -<p>Note that, depending on the APIs you use, your application might need to -request additional permissions in order to acquire device-specific information. -For example, to query the {@link android.telephony.TelephonyManager} to obtain -the device IMEI or related data, the application will also need to request the -<code>android.permission.READ_PHONE_STATE</code> permission in its manifest.</p> - -<p>Before requesting new permissions for the <em>sole purpose</em> of acquiring -device-specific information for use in your Obfuscator, consider -how doing so might affect your application or its filtering on Android Market -(since some permissions can cause the SDK build tools to add -the associated <code><uses-feature></code>).</p> - -<p>Finally, construct an instance of AESObfuscator, passing the salt, -application identifier, and device identifier. You can construct the instance -directly, while constructing your Policy and LicenseChecker. For example:</p> - -<pre> ... - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... -</pre> - -<p>For a complete example, see MainActivity in the LVL sample application.</p> - - -<h3 id="impl-lc">Checking the license from your application's main Activity</h3> - -<p>Once you've implemented a Policy for managing access to your application, the -next step is to add a license check to your application, which initiates a query -to the licensing server if needed and manages access to the application based on -the license response. All of the work of adding the license check and handling -the response takes place in your main {@link android.app.Activity} source file. -</p> - -<p>To add the license check and handle the response, you must:</p> - -<ol> - <li><a href="#imports">Add imports</a></li> - <li><a href="#lc-impl">Implement LicenseCheckerCallback</a> as a private inner class</li> - <li><a href="#thread-handler">Create a Handler</a> for posting from LicenseCheckerCallback to the UI thread</li> - <li><a href="#lc-lcc">Instantiate LicenseChecker</a> and LicenseCheckerCallback</li> - <li><a href="#check-access">Call checkAccess()</a> to initiate the license check</li> - <li><a href="#account-key">Embed your public key</a> for licensing</li> - <li><a href="#handler-cleanup">Call your LicenseChecker's onDestroy() method</a> to close IPC connections.</li> -</ol> - -<p>The sections below describe these tasks. </p> - -<h4 id="lc-overview">Overview of license check and response</h4> - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Example: MainActivity</h2> - -<p>The sample application included with the LVL provides a full example of how -to initiate a license check and handle the result, in the -<code>MainActivity.java</code> file.</p> - -</div> -</div> - -<p>In most cases, you should add the license check to your application's main -{@link android.app.Activity}, in the <code>onCreate()</code> method. This -ensures that when the user launches your application directly, the license check -will be invoked immediately. In some cases, you can add license checks in other -locations as well. For example, if your application includes multiple Activity -components that other applications can start by {@link android.content.Intent}, -you could add license checks in those Activities.</p> - -<p>A license check consists of two main actions: </p> - -<ul> -<li>A call to a method to initiate the license check — in the LVL, this is -a call to the <code>checkAccess()</code> method of a LicenseChecker object that -you construct.</li> -<li>A callback that returns the result of the license check. In the LVL, this is -a <code>LicenseCheckerCallback</code> interface that you implement. The -interface declares two methods, <code>allow()</code> and -<code>dontAllow()</code>, which are invoked by the library based on to the -result of the license check. You implement those two methods with whatever logic -you need, to allow or disallow the user access to your application. Note that -these methods do not determine <em>whether</em> to allow access — that -determination is the responsibility of your Policy implementation. Rather, these -methods simply provide the application behaviors for <em>how</em> to allow and -disallow access (and handle application errors).</li> -</ul> - -<div style="margin-bottom:2em;"> - -<img src="{@docRoot}images/licensing_flow.png" style="text-align:left;margin-bottom:0;margin-left:3em;" /> -<div style="margin:.5em 0 1.5em 2em;padding:0"><strong>Figure 6.</strong> Overview of a -typical license check interaction.</div> -</div> - -<p>The diagram above illustrates how a typical license check takes place: </p> - -<ol> -<li>Code in the application's main Activity instantiates LicenseCheckerCallback -and LicenseChecker objects. When constructing LicenseChecker, the code passes in -{@link android.content.Context}, a Policy implementation to use, and the -publisher account's public key for licensing as parameters. </li> -<li>The code then calls the <code>checkAccess()</code> method on the -LicenseChecker object. The method implementation calls the Policy to determine -whether there is a valid license response cached locally, in -{@link android.content.SharedPreferences}. -<ul> -<li>If so, the <code>checkAccess()</code> implementation calls -<code>allow()</code>.</li> -<li>Otherwise, the LicenseChecker initiates a license check request that is sent -to the licensing server.</li> -</ul> -<p class="note"><strong>Note:</strong> The licensing server always returns -<code>LICENSED</code> when you perform a license check of a draft application.</p> -</li> -<li>When a response is received, LicenseChecker creates a LicenseValidator that -verifies the signed license data and extracts the fields of the response, then -passes them to your Policy for further evaluation. - <ul> - <li>If the license is valid, the Policy caches the response in -SharedPreferences and notifies the validator, which then calls the -<code>allow()</code> method on the LicenseCheckerCallback object. </li> - <li>If the license not valid, the Policy notifies the validator, which calls -the <code>dontAllow()</code> method on LicenseCheckerCallback. </li> - </ul> -</li> -<li>In case of a recoverable local or server error, such as when the network is -not available to send the request, LicenseChecker passes a RETRY response to -your Policy's <code>processServerResponse()</code> method. </li> -<li>In case of a application error, such as when the application attempts to -check the license of an invalid package name, LicenseChecker passes an error -response to the LicenseCheckerCallback's <code>applicationError()</code> -method. </li> -</ol> - -<p>Note that, in addition to initiating the license check and handling the -result, which are described in the sections below, your application also needs -to provide a <a href="#impl-Policy">Policy implementation</a> and, if the Policy -stores response data (such as ServerManagedPolicy), an <a -href="#impl-Obfuscator">Obfuscator</a> implementation. </p> - - -<h4 id="imports">Add imports</h4> - -<p>First, open the class file of the application's main Activity and import -LicenseChecker and LicenseCheckerCallback from the LVL package.</p> - -<pre> import com.android.vending.licensing.LicenseChecker; - import com.android.vending.licensing.LicenseCheckerCallback;</pre> - -<p>If you are using the default Policy implementation provided with the LVL, -ServerManagedPolicy, import it also, together with the AESObfuscator. If you are -using a custom Policy or Obfuscator, import those instead. </p> - -<pre> import com.android.vending.licensing.ServerManagedPolicy; - import com.android.vending.licensing.AESObfuscator;</pre> - -<h4 id="lc-impl">Implement LicenseCheckerCallback as a private inner class</h4> - -<p>LicenseCheckerCallback is an interface provided by the LVL for handling -result of a license check. To support licensing using the LVL, you must -implement LicenseCheckerCallback and -its methods to allow or disallow access to the application.</p> - -<p>The result of a license check is always a call to one of the -LicenseCheckerCallback methods, made based on the validation of the response -payload, the server response code itself, and any additional processing provided -by your Policy. Your application can implement the methods in any way needed. In -general, it's best to keep the methods simple, limiting them to managing UI -state and application access. If you want to add further processing of license -responses, such as by contacting a backend server or applying custom constraints, -you should consider incorporating that code into your Policy, rather than -putting it in the LicenseCheckerCallback methods. </p> - -<p>In most cases, you should declare your implementation of -LicenseCheckerCallback as a private class inside your application's main -Activity class. </p> - -<p>Implement the <code>allow()</code> and <code>dontAllow()</code> methods as -needed. To start with, you can use simple result-handling behaviors in the -methods, such as displaying the license result in a dialog. This helps you get -your application running sooner and can assist with debugging. Later, after you -have determined the exact behaviors you want, you can add more complex handling. -</p> - -<p>Some suggestions for handling unlicensed responses in -<code>dontAllow()</code> include: </p> - -<ul> -<li>Display a "Try again" dialog to the user, including a button to initiate a -new license check. </li> -<li>Display a "Purchase this application" dialog, including a button that -deep-links the user to the application's details page on Market, from which the -use can purchase the application. For more information on how to set up such -links, see <a -href="{@docRoot}guide/publishing/publishing.html#marketintent">Using Intents to -Launch the Market Application on a Device</a>. </li> -<li>Display a Toast notification that indicates that the features of the -application are limited because it is not licensed. </li> -</ul> - -<p>The example below shows how the LVL sample application implements -LicenseCheckerCallback, with methods that display the license check result in a -dialog. </p> - -<pre> private class MyLicenseCheckerCallback implements LicenseCheckerCallback { - public void allow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - // Should allow user access. - displayResult(getString(R.string.allow)); - } - - public void dontAllow() { - if (isFinishing()) { - // Don't update UI if Activity is finishing. - return; - } - displayResult(getString(R.string.dont_allow)); - // Should not allow access. An app can handle as needed, - // typically by informing the user that the app is not licensed - // and then shutting down the app or limiting the user to a - // restricted set of features. - // In this example, we show a dialog that takes the user to Market. - showDialog(0); - } - } -</pre> - -<p>Additionally, you should implement the <code>applicationError()</code> -method, which the LVL calls to let your application handle errors that are not -retryable. For a list of such errors, see <a -href="#server-response-codes">Server Response Codes</a> in the Appendix of this -document. You can implement the method in any way needed. In most cases, the -method should log the error code and call <code>dontAllow()</code>.</p> - -<h4 id="thread-handler">Create a Handler for posting from LicenseCheckerCallback -to the UI thread</h4> - -<p>During a license check, the LVL passes the request to the Android Market -application, which handles communication with the licensing server. The LVL -passes the request over asynchronous IPC (using {@link android.os.Binder}) so -the actual processing and network communication do not take place on a thread -managed by your application. Similarly, when the Android Market application -receives the result, it invokes a callback method over IPC, which in turn -executes in an IPC thread pool in your application's process.</p> - -<p>The LicenseChecker class manages your application's IPC communication with -the Android Market application, including the call that sends the request and -the callback that receives the response. LicenseChecker also tracks open license -requests and manages their timeouts. </p> - -<p>So that it can handle timeouts properly and also process incoming responses -without affecting your application's UI thread, LicenseChecker spawns a -background thread at instantiation. In the thread it does all processing of -license check results, whether the result is a response received from the server -or a timeout error. At the conclusion of processing, the LVL calls your -LicenseCheckerCallback methods from the background thread. </p> - -<p>To your application, this means that:</p> - -<ol> -<li>Your LicenseCheckerCallback methods will be invoked, in many cases, from a -background thread.</li> -<li>Those methods won't be able to update state or invoke any processing in the -UI thread, unless you create a Handler in the UI thread and have your callback -methods post to the Handler.</li> -</ol> - -<p>If you want your LicenseCheckerCallback methods to update the UI thread, -instantiate a {@link android.os.Handler} in the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -as shown below. In this example, the LVL sample application's -LicenseCheckerCallback methods (see above) call <code>displayResult()</code> to -update the UI thread through the Handler's -{@link android.os.Handler#post(java.lang.Runnable) post()} method.</p> - -<pre>private Handler mHandler; - - @Override - public void onCreate(Bundle savedInstanceState) { - ... - mHandler = new Handler(); - } -</pre> - -<p>Then, in your LicenseCheckerCallback methods, you can use Handler methods to -post Runnable or Message objects to the Handler. Here's how the sample -application included in the LVL posts a Runnable to a Handler in the UI thread -to display the license status.</p> - -<pre> private void displayResult(final String result) { - mHandler.post(new Runnable() { - public void run() { - mStatusText.setText(result); - setProgressBarIndeterminateVisibility(false); - mCheckLicenseButton.setEnabled(true); - } - }); - } -</pre> - -<h4 id="lc-lcc">Instantiate LicenseChecker and LicenseCheckerCallback</h4> - -<p>In the main Activity's -{@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method, -create private instances of LicenseCheckerCallback and LicenseChecker. You must -instantiate LicenseCheckerCallback first, because you need to pass a reference -to that instance when you call the contructor for LicenseChecker. </p> - -<p>When you instantiate LicenseChecker, you need to pass in these parameters:</p> - -<ul> -<li>The application {@link android.content.Context}</li> -<li>A reference to the Policy implementation to use for the license check. In -most cases, you would use the default Policy implementation provided by the LVL, -ServerManagedPolicy. </li> -<li>The String variable holding your publisher account's public key for -licensing. </li> -</ul> - -<p>If you are using ServerManagedPolicy, you won't need to access the class -directly, so you can instantiate it in the LicenseChecker constructor, -as shown in the example below. Note that you need to pass a reference to a new -Obfuscator instance when you construct ServerManagedPolicy.</p> - -<p>The example below shows the instantiation of LicenseChecker and -LicenseCheckerCallback from the <code>onCreate()</code> method of an Activity -class. </p> - -<pre>public class MainActivity extends Activity { - ... - private LicenseCheckerCallback mLicenseCheckerCallback; - private LicenseChecker mChecker; - - @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Construct the LicenseCheckerCallback. The library calls this when done. - mLicenseCheckerCallback = new MyLicenseCheckerCallback(); - - // Construct the LicenseChecker with a Policy. - mChecker = new LicenseChecker( - this, new ServerManagedPolicy(this, - new AESObfuscator(SALT, getPackageName(), deviceId)), - BASE64_PUBLIC_KEY // Your public licensing key. - ); - ... - } -} -</pre> - - -<p>Note that LicenseChecker calls the LicenseCheckerCallback methods from the UI -thread <em>only</em> if there is valid license response cached locally. If the -license check is sent to the server, the callbacks always originate from the -background thread, even for network errors. </p> - - -<h4 id="check-access">Call checkAccess() to initiate the license check</h4> - -<p>In your main Activity, add a call to the <code>checkAccess()</code> method of the -LicenseChecker instance. In the call, pass a reference to your -LicenseCheckerCallback instance as a parameter. If you need to handle any -special UI effects or state management before the call, you might find it useful -to call <code>checkAccess()</code> from a wrapper method. For example, the LVL -sample application calls <code>checkAccess()</code> from a -<code>doCheck()</code> wrapper method:</p> - -<pre> @Override - public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - ... - // Call a wrapper method that initiates the license check - doCheck(); - ... - } - ... - private void doCheck() { - mCheckLicenseButton.setEnabled(false); - setProgressBarIndeterminateVisibility(true); - mStatusText.setText(R.string.checking_license); - mChecker.checkAccess(mLicenseCheckerCallback); - } -</pre> - - -<h4 id="account-key">Embed your public key for licensing</h4> - -<p>For each publisher account, the Android Market service automatically -generates a 2048-bit RSA public/private key pair that is used exclusively for -licensing. The key pair is uniquely associated with the publisher account and is -shared across all applications that are published through the account. Although -associated with a publisher account, the key pair is <em>not</em> the same as -the key that you use to sign your applications (or derived from it).</p> - -<p>The Android Market publisher site exposes the public key for licensing to any -developer signed in to the publisher account, but it keeps the private key -hidden from all users in a secure location. When an application requests a -license check for an application published in your account, the licensing server -signs the license response using the private key of your account's key pair. -When the LVL receives the response, it uses the public key provided by the -application to verify the signature of the license response. </p> - -<p>To add licensing to an application, you must obtain your publisher account's -public key for licensing and copy it into your application. Here's how to find -your account's public key for licensing:</p> - -<ol> -<li>Go to the Android Market <a -href="http://market.android.com/publish">publisher site</a> and sign in. -Make sure that you sign in to the account from which the application you are -licensing is published (or will be published). </li> -<li>In the account home page, locate the "Edit profile" link and click it. </li> -<li>In the Edit Profile page, locate the "Licensing" pane, shown below. Your -public key for licensing is given in the "Public key" text box. </li> -</ol> - -<p>To add the public key to your application, simply copy/paste the key string -from the text box into your application as the value of the String variable -<code>BASE64_PUBLIC_KEY</code>. When you are copying, make sure that you have -selected the entire key string, without omitting any characters. </p> - -<p>Here's an example from the LVL sample application:</p> - -<pre> public class MainActivity extends Activity { - private static final String BASE64_PUBLIC_KEY = "MIIBIjANBgkqhkiG ... "; //truncated for this example - ... - } -</pre> - -<h4 id="handler-cleanup">Call your LicenseChecker's onDestroy() method -to close IPC connections</h4> - -<p>Finally, to let the LVL clean up before your application -{@link android.content.Context} changes, add a call to the LicenseChecker's -<code>onDestroy()</code> method from your Activity's -{@link android.app.Activity#onDestroy()} implementation. The call causes the -LicenseChecker to properly close any open IPC connection to the Android Market -application's ILicensingService and removes any local references to the service -and handler.</p> - -<p>Failing to call the LicenseChecker's <code>onDestroy()</code> method -can lead to problems over the lifecycle of your application. For example, if the -user changes screen orientation while a license check is active, the application -{@link android.content.Context} is destroyed. If your application does not -properly close the LicenseChecker's IPC connection, your application will crash -when the response is received. Similarly, if the user exits your application -while a license check is in progress, your application will crash when the -response is received, unless it has properly called the -LicenseChecker's <code>onDestroy()</code> method to disconnect from the service. -</p> - -<p>Here's an example from the sample application included in the LVL, where -<code>mChecker</code> is the LicenseChecker instance:</p> - -<pre> @Override - protected void onDestroy() { - super.onDestroy(); - mChecker.onDestroy(); - ... - } -</pre> - -<p>If you are extending or modifying LicenseChecker, you might also need to call -the LicenseChecker's <code>finishCheck()</code> method, to clean up any open IPC -connections.</p> - -<h3 id="impl-DeviceLimiter">Implementing a DeviceLimiter</h3> - -<p>In some cases, you might want your Policy to limit the number of actual -devices that are permitted to use a single license. This would prevent a user -from moving a licensed application onto a number of devices and using the -application on those devices under the same account ID. It would also prevent a -user from "sharing" the application by providing the account information -associated with the license to other individuals, who could then sign in to that -account on their devices and access the license to the application. </p> - -<p>The LVL supports per-device licensing by providing a -<code>DeviceLimiter</code> interface, which declares a single method, -<code>allowDeviceAccess()</code>. When a LicenseValidator is handling a response -from the licensing server, it calls <code>allowDeviceAccess()</code>, passing a -user ID string extracted from the response.</p> - -<p>If you do not want to support device limitation, <strong>no work is -required</strong> — the LicenseChecker class automatically uses a default -implementation called NullDeviceLimiter. As the name suggests, NullDeviceLimiter -is a "no-op" class whose <code>allowDeviceAccess()</code> method simply returns -a <code>LICENSED</code> response for all users and devices. </p> - -<div style="border-left:4px solid #FFCF00;margin:1em;padding: 0 0 0 .5em"> -<p><strong>Caution:</strong> Per-device licensing is <em>not recommended for -most applications</em> because:</p> -<ul> -<li>It requires that you provide a backend server to manage a users and devices -mapping, and </li> -<li>It could inadvertently result in a user being denied access to an -application that they have legitimately purchased on another device.</li> -</ul> -</div> - - -<h2 id="test-env">Setting Up the Testing Environment</h2> - -<p>The Android Market publisher site provides configuration tools that let you -and others test licensing on your application before it is published. As you are -implementing licensing, you can make use of the publisher site tools to test -your application's Policy and handling of different licensing responses and -error conditions.</p> - -<p>The main components of the test environment for licensing include: </p> - -<ul> -<li>A "Test response" configuration in your publisher account that lets you -set the static licensing response returned, when the server processes a -license check for an application uploaded to the publisher account, from a user -signed in to the publisher account or a test account.</li> -<li>An optional set of test accounts that will receive the static test -response when they check the license of an application that you have uploaded -(regardless whether the application is published or not).</li> -<li>A runtime environment for the application that includes the Android Market -application or Google APIs Add-On, on which the user is signed in to the -publisher account or one of the test accounts.</li> -</ul> - -<p>Setting up the test environment properly involves:</p> - -<ol> -<li><a href="#test-response">Setting static test responses</a> that are returned by the licensing server.</li> -<li><a href="#test-acct-setup">Setting up test accounts</a> as needed.</li> -<li><a href="#acct-signin">Signing in</a> properly to an emulator or device, before initiating a license check test.</li> -</ol> - -<p>The sections below provide more information.</p> - - -<h3 id="test-response">Setting test responses for license checks</h3> - -<p>Android Market provides a configuration setting in your publisher account -that lets you override the normal processing of a license check and return a -specified static response code. The setting is for testing only and applies -<em>only</em> to license checks for applications that you have uploaded, made by -any user signed in to an emulator or device using the credentials of the -publisher account or a registered test account. For other users, the server -always processes license checks according to normal rules. </p> - -<p>To set a test response for your account, sign in to your publisher account -and click "Edit Profile". In the Edit Profile page, locate the Test Response -menu in the Licensing panel, shown below. You can select from the full set of -valid server response codes to control the response or condition you want to -test in your application.</p> - -<p>In general, you should make sure to test your application's licensing -implementation with every response code available in the Test Response menu. -For a description of the codes, see <a href="#server-response-codes">Server -Response Codes</a> in the Appendix of this document.</p> - -<div style="margin-bottom:2em;" id="licensing_test_response"> - -<img src="{@docRoot}images/licensing_test_response.png" style="text-align:left;margin-bottom:0;" /> -<div style="margin:0 2em;padding:0"><strong>Figure 7.</strong> The Licensing -panel of your account's Edit Profile page, showing the Test Accounts field and the -Test Response menu.</div> -</div> - -<p>Note that the test response that you configure applies account-wide — -that is, it applies not to a single application, but to <em>all</em> -applications associated with the publisher account. If you are testing multiple -applications at once, changing the test response will affect all of those -applications on their next license check (if the user is signed into -the emulator or device using the publisher account or a test account).</p> - -<p>Before you can successfully receive a test response for a license check, -you must sign in to the device or emulator on which the application -is installed, and from which it is querying the server. Specifically, you must -sign using either your publisher account or one of the test accounts that you -have set up. For more information about test accounts, see the next section.</p> - -<p>See <a href="#server-response-codes">Server Response Codes</a> for a list of -test responses available and their meanings. </p> - - -<h3 id="test-acct-setup">Setting up test accounts</h3> - -<p>In some cases, you might want to let multiple teams of developers test -licensing on applications that will ultimately be published through your -publisher account, but without giving them access to your publisher account's -sign-in credentials. To meet that need, the Android Market publisher site lets -you set up one or more optional <em>test accounts</em> — accounts that are -authorized to query the licensing server and receive static test responses from -your publisher account.</p> - -<p>Test accounts are standard Google accounts that you register on your -publisher account, such that they will receive the test response for -applications that you have uploaded. Developers can then sign in to their -devices or emulators using the test account credentials and initiate license -checks from installed applications. When the licensing server receives a license -check from a user of a test account, it returns the static test response -configured for the publisher account. </p> - -<p>Necessarily, there are limitations on the access and permissions given to -users signed in through test accounts, including:</p> - -<ul> -<li>Test account users can query the licensing server only for applications that -are already uploaded to the publisher account. </li> -<li>Test account users do not have permission to upload applications to your -publisher account.</li> -<li>Test account users do not have permission to set the publisher account's -static test response.</li> -</ul> - -<p>The table below summarizes the differences in capabilities, between the -publisher account, a test account, and any other account.</p> - -<p class="table-caption" id="acct-types-table"><strong>Table 1.</strong> -Differences in account types for testing licensing.</p> - -<table> -<tr> -<th>Account Type</th> -<th>Can check license before upload?</th> -<th>Can receive test response?</th> -<th>Can set test response?</th> -</tr> - -<tr> -<td>Publisher account</td> -<td>Yes</td> -<td>Yes</td> -<td>Yes</td> -</tr> - -<tr> -<td>Test account</td> -<td>No</td> -<td>Yes</td> -<td>No</td> -</tr> - -<tr> -<td>Other</td> -<td>No</td> -<td>No</td> -<td>No</td> -</tr> -</table> - -<h4 id="reg-test-acct">Registering test accounts on the publisher account</h4> - -<p>To get started, you need to register each test account in your publisher -account. As shown in <a href="#licensing_test_response">Figure 7</a>, above, you -register test accounts in the Licensing panel of your publisher account's Edit -Profile page. Simply enter the accounts as a comma-delimited list and click -<strong>Save</strong> to save your profile changes.</p> - -<p>You can use any Google account as a test account. If you want to own and -control the test accounts, you can create the accounts yourself and distribute -the credentials to your developers or testers.</p> - -<h4 id="test-app-upload">Handling application upload and distribution for test -account users</h4> - -<p>As mentioned above, users of test accounts can only receive static test -responses for applications that are uploaded to the publisher account. Since -those users do not have permission to upload applications, as the publisher you -will need to work with those users to collect apps for upload and distribute -uploaded apps for testing. You can handle collection and distribution in any way -that is convenient. </p> - -<p>Once an application is uploaded and becomes known to the licensing server, -developers and testers can continue modify the application in their local -development environment, without having to upload new versions. You only need to -upload a new version if the local application increments the -<code>versionCode</code> attribute in the manifest file. </p> - -<h4 id="test-key">Distributing your public key to test account users</h4> - -<p>The licensing server handles static test responses in the normal way, -including signing the license response data, adding extras parameters, and so -on. To support developers who are implementing licensing using test accounts, -rather than the publisher account, you will need to distribute -your public key to them. Developers without access to the publisher site do not -have access to your public key, and without the key they won't be able to -verify license responses. </p> - -<p>Note that if you decide to generate a new licensing key pair for your account -for some reason, you need to notify all users of test accounts. For -testers, you can embed the new key in the application package and distribute it -to users. For developers, you will need to distribute the new key to them -directly. </p> - - -<h3 id="acct-signin">Signing in to an authorized account in the runtime -environment</h3> - -<p>The licensing service is designed to determine whether a given user is -licensed to use a given application — during a license check, the Android -Market application gathers the user ID from the primary account on the system -and sends it to the server, together with the package name of the application -and other information. However, if there is no user information available, the -license check cannot succeed, so the Android Market application terminates the -request and returns an error to the application. </p> - -<p>During testing, to ensure that your application can successfully query the -licensing server, you must make sure that you sign in to an account <em>on the -device or emulator</em> using:</p> - -<ul> -<li>The credentials of a publisher account, or</li> -<li>The credentials of a test account that is registered with a publisher -account</li> -</ul> - - -<div class="sidebox-wrapper"> -<div class="sidebox"> -<h2>Signing in to a Google account on an emulator</h2> - -<p>If you are testing licensing on an emulator, you need to sign in to a Google -account on the emulator. If you do not see an option to create a new Google -account, the problem might be that your AVD is running a standard Android system -image, rather than the Google APIs Add-On, API 8 (release 2) or higher. </p> - -<p style="margin-top:.5em;">For more information, see <a -href="#runtime-setup">Setting up the runtime environment</a>, above.</p> - -</div> -</div> - -<p>Signing in using a publisher account offers the advantage of letting your -applications receive static test responses even before the applications are -uploaded to the publisher site.</p> - -<p>If you are part of a larger organization or are working with external groups -on applications that will be published through your site, you will more likely -want to distribute test accounts instead, then use those to sign in during -testing. </p> - -<p>To sign in on a device or emulator, follow the steps below. The preferred -approach is to sign in as the primary account — however, if there are -other accounts already in use on the device or emulator, you can create an -additional account and sign in to it using the publisher or test account -credentials. </p> - -<ol> -<li>Open Settings > Accounts & sync</li> -<li>Select <strong>Add Account</strong> and choose to add a "Google" account. -</li> -<li>Select <strong>Next</strong> and then <strong>Sign in</strong>.</li> -<li>Enter the username and password of either the publisher account or a test -account that is registered in the publisher account.</li> -<li>Select <strong>Sign in</strong>. The system signs you in to the new -account.</li> -</ol> - -<p>Once you are signed in, you can begin testing licensing in your application -(if you have completed the LVL integration steps above). When your application -initiates a license check, it will receive a response containing the static test -response configured on the publisher account. </p> - -<p>Note that, if you are using an emulator, you will need to sign in to the -publisher account or test account each time you wipe data when restarting the -emulator.</p> - -<div style="margin:2em 1em 1em 1em;"> - -<img src="{@docRoot}images/licensing_device_signin.png" style="text-align:left;" /> -<div style="margin:.25em 1.25em;padding:0"><strong>Figure 8.</strong> Example of -setting up a Google account on a device or emulator.</div> -</div> - -<h2 id="app-obfuscation">Obfuscating Your Application</h2> - -<p>To ensure the security of your application, particularly for a paid -application that uses licensing and/or custom constraints and protections, it's -very important to obfuscate your application code. Properly obfuscating your -code makes it more difficult for a malicious user to decompile the application's -bytecode, modify it — such as by removing the license check — -and then recompile it.</p> - -<p>Several obfuscator programs are available for Android applications, including -<a href="http://proguard.sourceforge.net/">ProGuard</a>, which also offers -code-optimization features. The use of ProGuard or a similar program to obfuscate -your code is <em>strongly recommended</em> for all applications that use Android -Market Licensing. </p> - -<h2 id="app-publishing">Publishing a Licensed Application</h2> - -<p>When you are finished testing your license implementation, you are ready to -publish the application on Android Market. Follow the normal steps to <a -href="{@docRoot}guide/publishing/preparing.html">prepare</a>, <a -href="{@docRoot}guide/publishing/app-signing.html">sign</a>, and then <a -href="{@docRoot}guide/publishing/publishing.html">publish the application</a>. -</p> - -<h4>Removing Copy Protection</h4> - -<p>After uploading your licensed application, remember to remove copy protection -from the application, if it is currently used. To check and remove copy -protection, sign in to the publisher site and go the application's upload -details page. In the Publishing options section, make sure that the Copy -Protection radio button selection is "Off".</p> - -<h4>Considerations for Free Apps</h4> - -<p>Licensing is currently supported only for paid applications. If you already -published your application as free, you won't be able to upload an updated -version that includes licensing (that is, an application that uses the same -package name and that includes the <a href="#manifest-permission">licensing -permission</a>). Here are some points to keep in mind:</p> - -<ul> -<li>If you want to offer a free version of your application that provides a -reduced feature set (or that offers the full feature set for trial period), the -free version of your application must not include the licensing permission and -must use a different package name than the paid version of the app.</li> -<li>If you want to offer a paid version of your free application that uses -licensing, you can do so under a new package name.</li> -</ul> - -<h2 id="support">Where to Get Support</h2> - -<p>If you have questions or encounter problems while implementing or deploying -publishing in your applications, please use the support resources listed in the -table below. By directing your queries to the correct forum, you can get the -support you need more quickly. </p> - -<p class="table-caption"><strong>Table 2.</strong> Developer support resources -for Android Market Licensing Service.</p> - -<table> - -<tr> -<th>Support Type</th> -<th>Resource</th> -<th>Range of Topics</th> -</tr> -<tr> -<td rowspan="2">Development and testing issues</td> -<td>Google Groups: <a -href="http://groups.google.com/group/android-developers">android-developers</a> -</td> -<td rowspan="2">LVL download and integration, library projects, Policy -questions, user experience ideas, handling of responses, Obfuscator, IPC, test -environment setup</td> -</tr> -<tr> -<td>Stack Overflow: <a -href="http://stackoverflow.com/questions/tagged/android">http://stackoverflow.com/questions/tagged/android</a></td> -</tr> -<tr> -<td rowspan="2">Accounts, publishing, and deployment issues</td> -<td><a href="http://www.google.com/support/forum/p/Android+Market">Android -Market Help Forum</a></td> -<td rowspan="2">Publisher accounts, licensing key pair, test accounts, server -responses, test responses, application deployment and results</td> -</tr> -<tr> -<td><a -href="http://market.android.com/support/bin/answer.py?answer=186113">Market -Licensing Support FAQ</a></td> -</tr> -<tr> -<td>LVL issue tracker</td> -<td><a href="http://code.google.com/p/marketlicensing/issues/">Marketlicensing -project issue tracker</a></td> -<td>Bug and issue reports related specifically to the LVL source code classes -and interface implementations</td> -</tr> - -</table> - -<p>For general information about how to post to the groups listed above, see <a -href="{@docRoot}resources/community-groups.html">Developer Forums</a> document -in the Resources tab.</p> - -<h2 id="lvl-summary">Summary of LVL Classes and Interfaces</h2> - -<p>The table below lists all of the source files in the License Verification -Library (LVL) available through the Android SDK. All of the files are part of -the <code>com.android.vending.licensing</code> package.</p> - -<p class="table-caption"><strong>Table A-1.</strong> Summary of LVL library -classes and interfaces.</p> - -<div style="width:99%"> -<table width="100%"> - -<tr> -<th width="15%">Category</th> -<th width="20%">Name</th> -<th width="100%">Description</th> -</tr> - -<tr> -<td rowspan="2">License check and result</td> -<td>LicenseChecker</td> -<td>Class that you instantiate (or subclass) to initiate a license check.</td> -</tr> -<tr> -<td><em>LicenseCheckerCallback</em></td> -<td>Interface that you implement to handle result of the license check.</td> -</tr> - -<tr> -<td rowspan="3" width="15%">Policy</td> -<td width="20%"><em>Policy</em></td> -<td width="100%">Interface that you implement to determine whether to allow -access to the application, based on the license response. </td> -</tr> -<tr> -<td>ServerManagedPolicy</td> -<td width="100%">Default Policy implementation. Uses settings provided by the -licensing server to manage local storage of license data, license validity, -retry.</td> -</tr> -<tr> -<td>StrictPolicy</td> -<td>Alternative Policy implementation. Enforces licensing based on a direct -license response from the server only. No caching or request retry.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Data obfuscation <br><em>(optional)</em></td> -<td width="20%"><em>Obfuscator</em></td> -<td width="100%">Interface that you implement if you are using a Policy (such as -ServerManagedPolicy) that caches license response data in a persistent store. -Applies an obfuscation algorithm to encode and decode data being written or -read.</td> -</tr> -<tr> -<td>AESObfuscator</td> -<td>Default Obfuscator implementation that uses AES encryption/decryption -algorithm to obfuscate/unobfuscate data.</td> -</tr> - -<tr> -<td rowspan="2" width="15%">Device limitation<br><em>(optional)</em></td> -<td width="20%"><em>DeviceLimiter</em></td> -<td width="100%">Interface that you implement if you want to restrict use of an -application to a specific device. Called from LicenseValidator. Implementing -DeviceLimiter is not recommended for most applications because it requires a -backend server and may cause the user to lose access to licensed applications, -unless designed with care.</td> -</tr> -<tr> -<td>NullDeviceLimiter</td> -<td>Default DeviceLimiter implementation that is a no-op (allows access to all -devices).</td> -</tr> - -<tr> -<td rowspan="6" width="15%">Library core, no integration needed</td> -<td width="20%">ResponseData</td> -<td width="100%">Class that holds the fields of a license response.</td> -</tr> -<tr> -<td>LicenseValidator</td> -<td>Class that decrypts and verifies a response received from the licensing -server.</td> -</tr> -<tr> -<td>ValidationException</td> -<td>Class that indicates errors that occur when validating the integrity of data -managed by an Obfuscator.</td> -</tr> -<tr> -<td>PreferenceObfuscator</td> -<td>Utility class that writes/reads obfuscated data to the system's -{@link android.content.SharedPreferences} store.</td> -</tr> -<tr> -<td><em>ILicensingService</em></td> -<td>One-way IPC interface over which a license check request is passed to the -Android Market client.</td> -</tr> -<tr> -<td><em>ILicenseResultListener</em></td> -<td>One-way IPC callback implementation over which the application receives an -asynchronous response from the licensing server.</td> -</tr> - -</table> -</div> - - -<h2 id="server-response-codes">Server Response Codes</h2> - -<p>The table below lists all of the license response codes supported by the -licensing server. In general, an application should handle all of these response -codes. By default, the LicenseValidator class in the LVL provides all of the -necessary handling of these response codes for you. </p> - -<p class="table-caption"><strong>Table A-2.</strong> Summary of response codes -returned by the Android Market server in a license response.</p> - -<table> - -<tr> -<th>Response Code</th> -<th>Description</th> -<th>Signed?</th> -<th>Extras</th> -<th>Comments</th> -</tr> -<tr> -<td>LICENSED</td> -<td>The application is licensed to the user. The user has purchased the -application or the application only exists as a draft.</td> -<td>Yes</td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code></td> -<td><em>Allow access according to Policy constraints.</em></td> -</tr> -<tr> -<td>LICENSED_OLD_KEY</td> -<td>The application is licensed to the user, but there is an updated application -version available that is signed with a different key. </td> -<td>Yes </td> -<td><code>VT</code>, <code>GT</code>, <code>GR</code>, <code>UT</code></td> -<td><em>Optionally allow access according to Policy constraints.</em> -<p style="margin-top:.5em;">Can indicate that the key pair used by the installed -application version is invalid or compromised. The application can allow access -if needed or inform the user that an upgrade is available and limit further use -until upgrade.</p> -</td> -</tr> -<tr> -<td>NOT_LICENSED</td> -<td>The application is not licensed to the user.</td> -<td>No</td> -<td></td> -<td><em>Do not allow access.</em></td> -</tr> -<tr> -<td>ERROR_CONTACTING_SERVER</td> -<td>Local error — the Android Market application was not able to reach the -licensing server, possibly because of network availability problems. </td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em></td> -</tr> -<tr> -<td>ERROR_SERVER_FAILURE</td> -<td>Server error — the server could not load the publisher account's key -pair for licensing.</td> -<td>No</td> -<td></td> -<td><em>Retry the license check according to Policy retry limits.</em> -</td> -</tr> -<tr> -<td>ERROR_INVALID_PACKAGE_NAME</td> -<td>Local error — the application requested a license check for a package -that is not installed on the device. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NON_MATCHING_UID</td> -<td>Local error — the application requested a license check for a package -whose UID (package, user ID pair) does not match that of the requesting -application. </td> -<td>No </td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Typically caused by a development error.</p> -</td> -</tr> -<tr> -<td>ERROR_NOT_MARKET_MANAGED</td> -<td>Server error — the application (package name) was not recognized by -Android Market. </td> -<td>No</td> -<td></td> -<td><em>Do not retry the license check.</em> -<p style="margin-top:.5em;">Can indicate that the application was not published -through Android Market or that there is an development error in the licensing -implementation.</p> -</td> -</tr> - -</table> - -<p class="note"><strong>Note:</strong> As documented in <a href="#test-env"> -Setting Up The Testing Environment</a>, the response code can be manually -overridden for the application developer and any registered test users via the -Android Market publisher site. -<br/><br/> -Additionally, as noted above, applications that are in draft mode (in other -words, applicaitons that have been uploaded but have <em>never</em> been -published) will return LICENSED for all users, even if not listed as a test -user. Since the application has never been offered for download, it is assumed -that any users running it must have obtained it from an authorized channel for -testing purposes.</p> - -<h2 id="extras">Server Response Extras</h2> - -<p>The licensing server includes several settings in certain types of license -responses, to assist the application and its Policy in managing access to the -application across the 24-hour refund period and other conditions. Specifically, -the server provides recommended values for the application's license validity -period, retry grace period, maximum allowable retry count, and other settings. -The server appends the settings as key-value pairs in the license response -"extras" field. </p> - -<p>Any Policy implementation can extract the extras settings from the license -response and use them as needed. The LVL default Policy implementation, <a -href="#ServerManagedPolicy">ServerManagedPolicy</a>, serves as a working -implementation and an illustration of how to obtain, store, and use the -settings. </p> - -<p class="table-caption"><strong>Table A-3.</strong> Summary of -license-management settings supplied by the Android Market server in a license -response.</p> - -<table> -<tr> -<th>Extra</th><th>Description</th> -</tr> - -<tr> - <td>VT</td> - <td>License validity timestamp. Specifies the date/time at which the current -(cached) license response expires and must be rechecked on the licensing server. - </td> -</tr> -<tr> - <td>GT</td> - <td>Grace period timestamp. Specifies the end of the period during which a -Policy may allow access to the application, even though the response status is -RETRY. <p>The value is managed by the server, however a typical value would be 5 -or more days.</p></td> -</tr> -<tr> - <td>GR</td> - <td>Maximum retries count. Specifies how many consecutive RETRY license checks -the Policy should allow, before denying the user access to the application. -<p>The value is managed by the server, however a typical value would be "10" or -higher.</p></td> -</tr> -<tr> - <td>UT</td> - <td>Update timestamp. Specifies the day/time when the most recent update to -this application was uploaded and published. <p>The server returns this extra -only for LICENSED_OLD_KEYS responses, to allow the Policy to determine how much -time has elapsed since an update was published with new licensing keys before -denying the user access to the application. </p></td> -</tr> - -</table> - -<p>The sections below provide more information about the server-provided -settings and how to use them. </p> - -<h4>License validity period</h4> - -<p>The Android Market licensing server sets a license validity period for all -downloaded applications. The period expresses the interval of time over which an -application's license status should be considered as unchanging and cacheable by -a licensing Policy in the application. The licensing server includes the -validity period in its response to all license checks, appending an -end-of-validity timestamp to the response as an extra under the key "VT". A -Policy can extract the VT key value and use it to conditionally allow access to -the application without rechecking the license, until the validity period -expires. </p> - -<p>The license validity signals to a licensing Policy when it must recheck the -licensing status with the licensing server. It is <em>not</em> intended to imply -whether an application is actually licensed for use. That is, when an -application's license validity period expires, this does not mean that the -application is no longer licensed for use — rather, it indicates only that -the Policy must recheck the licensing status with the server. It follows that, -as long as the license validity period is not expired, it is acceptable for the -Policy to cache the initial license status locally and return the cached license -status instead of sending a new license check to the server.</p> - -<p>The licensing server manages the validity period as a means of helping the -application properly enforce licensing across the refund period offered by -Android Market for paid applications. It sets the validity period based on -whether the application was purchased and, if so, how long ago. Specifically, -the server sets a validity period as follows:</p> - -<ul> -<li>For a paid application, the server sets the initial license validity period -so that the license response remains valid for as long as the application is -refundable. A licensing Policy in the application may cache the -result of the initial license check and does not need to recheck the license -until the validity period has expired.</li> -<li>When an application is no longer refundable, the server -sets a longer validity period — typically a number of days. </li> -<li>For a free application, the server sets the validity period to a very high -value (<code>long.MAX_VALUE</code>). This ensures that, provided the Policy has -cached the validity timestamp locally, it will not need to recheck the -license status of the application in the future.</li> -</ul> - -<p>The ServerManagedPolicy implementation uses the extracted timestamp -(<code>mValidityTimestamp</code>) as a primary condition for determining whether -to recheck the license status with the server before allowing the user access to -the application. </p> - -<h4>Retry period and maximum retry count</h4> - -<p>In some cases, system or network conditions can prevent an application's -license check from reaching the licensing server, or prevent the server's -response from reaching the Android Market client application. For example, the -user might launch an application when there is no cell network or data -connection available — such as when on an airplane — or when the -network connection is unstable or the cell signal is weak. </p> - -<p>When network problems prevent or interrupt a license check, the Android -Market client notifies the application by returning a "RETRY" response code to -the Policy's <code>processServerResponse()</code> method. In the case of system -problems, such as when the application is unable to bind with Android Market's -ILicensingService implementation, the LicenseChecker library itself calls the -Policy <code>processServerResonse()</code> method with a "RETRY" response code. -</p> - -<p>In general, the RETRY response code is a signal to the application that an -error has occurred that has prevented a license check from completing. - -<p>The Android Market server helps an application to manage licensing under -error conditions by setting a retry "grace period" and a recommended maximum -retries count. The server includes these values in all license check responses, -appending them as extras under the keys "GT" and "GR". </p> - -<p>The application Policy can extract the GT and GR extras and use them to -conditionally allow access to the application, as follows:</p> - -<ul> -<li>For a license check that results in a RETRY response, the Policy should -cache the RETRY response code and increment a count of RETRY responses.</li> -<li>The Policy should allow the user to access the application, provided that -either the retry grace period is still active or the maximum retries count has -not been reached.</li> -</ul> - -<p>The ServerManagedPolicy uses the server-supplied GT and GR values as -described above. The example below shows the conditional handling of the retry -responses in the <code>allow()</code> method. The count of RETRY responses is -maintained in the <code>processServerResponse()</code> method, not shown. </p> - - -<pre> public boolean allowAccess() { - long ts = System.currentTimeMillis(); - if (mLastResponse == LicenseResponse.LICENSED) { - // Check if the LICENSED response occurred within the validity timeout. - if (ts <= mValidityTimestamp) { - // Cached LICENSED response is still valid. - return true; - } - } else if (mLastResponse == LicenseResponse.RETRY && - ts < mLastResponseTime + MILLIS_PER_MINUTE) { - // Only allow access if we are within the retry period or we haven't used up our - // max retries. - return (ts <= mRetryUntil || mRetryCount <= mMaxRetries); - } - return false; - }</pre> - diff --git a/docs/html/guide/publishing/preparing.jd b/docs/html/guide/publishing/preparing.jd index 83aa5ee..fe56352 100644 --- a/docs/html/guide/publishing/preparing.jd +++ b/docs/html/guide/publishing/preparing.jd @@ -22,7 +22,7 @@ page.title=Preparing for Release <ol> <li><a href="{@docRoot}guide/publishing/publishing_overview.html">Publishing Overview</a></li> <li><a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -39,13 +39,13 @@ similar to the debug build process and can be done using JDK and Android SDK too tasks serve as a final check, ensuring that your application performs as expected under real-world conditions. When you are finished preparing your application for release you have a signed <code>.apk</code> file, which you can distribute directly to users or distribute through an -application marketplace such as Android Market.</p> +application marketplace such as Google Play.</p> <p>This document summarizes the main tasks you need to perform to prepare your application for release. The tasks that are described in this document apply to all Android applications regardless -how they are released or distributed to users. If you are releasing your application through Android -Market, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on -Android Market</a> to be sure your release-ready application satisfies all Android Market +how they are released or distributed to users. If you are releasing your application through Google +Play, you should also read <a href="{@docRoot}guide/publishing/publishing.html">Publishing on +Google Play</a> to be sure your release-ready application satisfies all Google Play requirements.</p> <p class="note"><strong>Note:</strong> As a best practice, your application should meet all of your @@ -89,9 +89,9 @@ line.</p> <p>To prepare your application for release you typically perform five main tasks (see figure 2). Each main task may include one or more smaller tasks depending on how you are releasing your -application. For example, if you are releasing your application through Android Market you may want +application. For example, if you are releasing your application through Google Play you may want to add special filtering rules to your manifest while you are configuring your application for -release. Similarly, to meet Android Market publishing guidelines you may have to prepare screenshots +release. Similarly, to meet Google Play publishing guidelines you may have to prepare screenshots and create promotional text while you are gathering materials for release.</p> <p>You usually perform the tasks listed in figure 2 after you have throroughly debugged and tested @@ -137,9 +137,9 @@ key</a>.</p> href="{@docRoot}guide/practices/ui_guidelines/icon_design_launcher.html">icon guidelines</a>. Your application's icon helps users identify your application on a device's Home screen and in the Launcher window. It also appears in Manage Applications, My Downloads, and -elsewhere. In addition, publishing services such as Android Market display your icon to users.</p> +elsewhere. In addition, publishing services such as Google Play display your icon to users.</p> -<p class="note"><strong>Note:</strong> If you are releasing your application on Android Market, you +<p class="note"><strong>Note:</strong> If you are releasing your application on Google Play, you need to create a high resolution version of your icon. See <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870">Graphic @@ -154,7 +154,7 @@ with your application.</p> <h4>Miscellaneous Materials</h4> <p>You might also have to prepare promotional and marketing materials to publicize your application. -For example, if you are releasing your application on Android Market you will need to prepare some +For example, if you are releasing your application on Google Play you will need to prepare some promotional text and you will need to create screenshots of your application. For more information, see <a href="https://www.google.com/support/androidmarket/developer/bin/answer.py?answer=1078870"> @@ -242,11 +242,11 @@ tasks:</p> </ul> <p>There are several additional manifest elements that you can set if you are releasing your -application on Android Market. For example, the <code>android:minSdkVersion</code> and +application on Google Play. For example, the <code>android:minSdkVersion</code> and <code>android:targetSdkVersion</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"> <uses-sdk></a> element. For more -information about these and other Android Market settings, see <a -href="{@docRoot}/guide//appendix/market-filters.html">Market Filters</a>.</p> +information about these and other Google Play settings, see <a +href="{@docRoot}/guide//appendix/market-filters.html">Filters on Google Play</a>.</p> <h4>Address compatibility issues</h4> @@ -283,15 +283,15 @@ doing the following:</p> <p>If your application accesses remote servers or services, make sure you are using the production URL or path for the server or service and not a test URL or path.</p> -<h4>Implement Licensing (if you are releasing on Android Market)</h4> +<h4>Implement Licensing (if you are releasing on Google Play)</h4> -<p>If you are releasing a paid application through Android Market, consider adding support for -Android Market Licensing. Licensing lets you control access to your application based on whether the -current user has purchased it. Using Android Market Licensing is optional even if you are -releasing your app through Android Market.</p> +<p>If you are releasing a paid application through Google Play, consider adding support for +Google Play Licensing. Licensing lets you control access to your application based on whether the +current user has purchased it. Using Google Play Licensing is optional even if you are +releasing your app through Google Play.</p> -<p>For more information about Android Market Licensing Service and how to use it in your -application, see <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +<p>For more information about Google Play Licensing Service and how to use it in your +application, see <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a>.</p> <h2 id="publishing-build">Building Your Application for Release</h2> @@ -352,7 +352,7 @@ a summary of common Android situations that you should consider when you are tes done testing and you are satisfied that the release version of your application behaves correctly, you can release your application to users. For more information, see <a href="{@docRoot}guide/publishing/publishing_overview.html#publishing-release">Releasing Your -Application to Users</a>. If you are publishing your application on Android Market, see -<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a>.</p> +Application to Users</a>. If you are publishing your application on Google Play, see +<a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a>.</p> diff --git a/docs/html/guide/publishing/publishing.jd b/docs/html/guide/publishing/publishing.jd index 49b34d8..b9513ab 100644 --- a/docs/html/guide/publishing/publishing.jd +++ b/docs/html/guide/publishing/publishing.jd @@ -1,4 +1,4 @@ -page.title=Publishing on Android Market +page.title=Publishing on Google Play @jd:body <div id="qv-wrapper"> @@ -7,25 +7,25 @@ page.title=Publishing on Android Market <h2>Quickview</h2> <ul> -<li>Learn how to publish and update apps on Android Market.</li> -<li>Find out how to create links to apps that are published on Android Market.</li> -<li>Learn about Android Market features.</li> +<li>Learn how to publish and update apps on Google Play.</li> +<li>Find out how to create links to apps that are published on Google Play.</li> +<li>Learn about Google Play features.</li> </ul> <h2>In this document</h2> <ol> -<li><a href="#overview">About Android Market</a> -<li><A href="#marketpublish">Publishing Apps on Android Market</a></li> -<li><a href="#marketupgrade">Publishing Updates on Android Market</a></li> -<li><a href="#marketLicensing">Using Android Market Licensing Service</a></li> -<li><a href="#marketinappbilling">Using Android Market In-app Billing</a></li> -<li><a href="#marketintent">Linking to Your Apps on Android Market</a> +<li><a href="#overview">About Google Play</a> +<li><A href="#marketpublish">Publishing Apps on Google Play</a></li> +<li><a href="#marketupgrade">Publishing Updates on Google Play</a></li> +<li><a href="#marketLicensing">Using Google Play Licensing Service</a></li> +<li><a href="#marketinappbilling">Using Google Play In-app Billing</a></li> +<li><a href="#marketintent">Linking to Your Apps on Google Play</a> <ol> <li><a href="#OpeningDetails">Opening an app's details page</a></li> <li><a href="#PerformingSearch">Performing a search</a></li> - <li><a href="#BuildaButton">Build an Android Market button</a></li> + <li><a href="#BuildaButton">Build a Google Play button</a></li> <li><a href="#UriSummary">Summary of URI formats</a></li> </ol> </li> @@ -41,9 +41,9 @@ page.title=Publishing on Android Market <div id="qv-extra"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0 5px;"> - <h2 style="color:#669999;">Already know about Android Market and want to get started?</h2> - <p>Go to <a href="http://market.android.com/publish">Android Market</a>, create a developer + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0 5px;"> + <h2 style="color:#669999;">Already know about Google Play and want to get started?</h2> + <p>Go to <a href="http://play.google.com/apps/publish">Google Play</a>, create a developer account, and upload your application. For more information about required assets, listing details, and publishing options, see <a href="http://market.android.com/support/bin/answer.py?answer=113469">Upload @@ -55,78 +55,78 @@ Applications</a>.</p> </div> <p>One of the most effective ways to get your application into users' hands is to -publish it on an application marketplace like Android Market. Publishing on Android Market is a +publish it on an application marketplace like Google Play. Publishing on Google Play is a straightforward process that you can do in just a few simple steps—register, configure, upload, and publish. Registration takes only a few minutes and needs to be done only once. -The configuration and publishing steps can all be done through the Android Market Developer Console -after you register as an Android Market developer.</p> +The configuration and publishing steps can all be done through the Google Play Android Developer Console +after you register as a Google Play developer.</p> -<p>To start publishing on Android Market, first read this topic and then go to the <a -href="https://market.android.com/publish/signup">Android Market publisher site</a> and register as -an Android Market developer.</p> +<p>To start publishing on Google Play, first read this topic and then go to the <a +href="https://play.google.com/apps/publish">Google Play Android Developer Console</a> and register as +a Google Play developer.</p> -<h2 id="overview">About Android Market</h2> +<h2 id="overview">About Google Play</h2> -<p>Android Market is a robust publishing platform that helps you publicize, sell, and distribute +<p>Google Play is a robust publishing platform that helps you publicize, sell, and distribute your Android applications to users around the world. When you release your applications through -Android Market you have access to a suite of developer tools that let you analyze your sales, +Google Play you have access to a suite of developer tools that let you analyze your sales, identify market trends, and control who your applications are being distributed to. You also have access to several revenue-enhancing features, such as <a href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and -<a href="{@docRoot}guide/publishing/licensing.html">application licensing</a>.</p> +<a href="{@docRoot}guide/market/licensing/index.html">application licensing</a>.</p> -<p>Before you can publish applications on Android Market, you need to <a -href="http://market.android.com/publish">register</a> as an Android Market developer. During the +<p>Before you can publish applications on Google Play, you need to <a +href="http://play.google.com/apps/publish">register</a> as a Google Play developer. During the registration process you will need to create a developer profile, pay a registration fee, and agree -to the <a href="http://www.android.com/us/developer-distribution-agreement.html">Android Market -Developer Distribution Agreement</a>. After you register you can access the Android Market Developer +to the <a href="http://www.android.com/us/developer-distribution-agreement.html">Google Play +Developer Distribution Agreement</a>. After you register you can access the Developer Console, where you can upload applications, configure publishing options, and monitor publishing data. If you want to sell your applications or use the in-app billing feature, you will also need to set up a Google Checkout merchant account. For more information about the registration process, see <a href="https://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=113468"> Developer Registration</a>.</p> -<h2 id="marketpublish">Publishing Apps on Android Market</h2> +<h2 id="marketpublish">Publishing Apps on Google Play</h2> -<p>Publishing your application on Android Market is a simple process that involves three basic +<p>Publishing your application on Google Play is a simple process that involves three basic tasks (see figure 1):</p> <ul> <li>Creating various graphical assets that -accompany your app on Android Market.</li> - <li>Using the Android Market <a -href="http://market.android.com/publish">Developer Console</a> to configure publishing options, -specify listing details, and upload your app and graphical assets to Android Market.</li> +accompany your app on Google Play.</li> + <li>Using the Google Play <a +href="http://play.google.com/apps/publish">Developer Console</a> to configure publishing options, +specify listing details, and upload your app and graphical assets to Google Play.</li> <li>Reviewing your publishing settings and changing the release status of your app from Unpublished to Published.</li> </ul> <img src="{@docRoot}images/publishing/publishing_android_market.png" - alt="Shows the three steps that are required to publish on Android Market" + alt="Shows the three steps that are required to publish on Google Play" height="168" id="figure1" /> <p class="img-caption"> - <strong>Figure 1.</strong> To publish apps on Android Market you must first <a + <strong>Figure 1.</strong> To publish apps on Google Play you must first <a href="{@docRoot}guide/publishing/preparing.html">prepare your app for release</a> and then perform three simple tasks. </p> <p class="caution"><strong>Important:</strong> You must <a href="{@docRoot}guide/publishing/preparing.html">prepare your application for release</a> before you -can publish it on Android Market. When you prepare your application for release you configure it for +can publish it on Google Play. When you prepare your application for release you configure it for release and build it in release mode. Building in release mode signs your application's {@code .apk} -file with your private release key. You cannot publish an application on Android Market unless it is +file with your private release key. You cannot publish an application on Google Play unless it is signed with your own private release key.</p> <h3>Preparing promotional materials</h3> -<p>To fully leverage the marketing and publicity capabilities of Android Market, you need to create -several graphical assets that accompany your app on Android Market, such as screenshots, videos, +<p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create +several graphical assets that accompany your app on Google Play, such as screenshots, videos, promotional graphics, and promotional text. At a minimum you must provide two screenshots of your application and a high resolution application icon. The screenshots are displayed on the details -page for your application in Android Market, and the high resolution application icon is displayed -in various locations throughout Android Market. The high resolution icon does not replace the +page for your application on Google Play, and the high resolution application icon is displayed +in various locations throughout Google Play. The high resolution icon does not replace the launcher icon for your application, rather, it serves as a supplemental icon and should look the same as your launcher icon. Promotional video, graphics, and text are optional, although we strongly recommended that you prepare these for your @@ -136,8 +136,8 @@ Assets for your Application</a>.</p> <h3>Configuring options and uploading assets</h3> -<p>Android Market lets you target your application to a worldwide pool of users and devices. To -reach these users you can use the Android Market Developer Console to configure various publishing +<p>Google Play lets you target your application to a worldwide pool of users and devices. To +reach these users you can use the Developer Console to configure various publishing options and listing details for your app. For example, you can choose the <a href="http://support.google.com/androidmarket/developer/bin/answer.py?hl=en&answer=138294&topic= 2365624&ctx=topic">countries</a> you want to reach, the listing languages you want to use, and the @@ -155,11 +155,11 @@ href="http://grendel.sea.corp.google.com:48014/guide/market/billing/billing_admi app.</p> <p>When you are finished setting publishing options and listing details, you can upload your assets -and your application to Android Market. You can also upload your application as a draft +and your application to Google Play. You can also upload your application as a draft (unpublished) application, which lets you do final testing before you publish it for final release.</p> -<p>To learn more about Android Market publishing settings, see the following resources:</p> +<p>To learn more about Google Play publishing settings, see the following resources:</p> <ul> <li><a @@ -181,20 +181,20 @@ pricing, payouts, and exchange rates work.</li> <p>When you are satisfied that your publishing settings are correctly configured and your uploaded application is ready to be released to the public, you can simply click <strong>Publish</strong> in the Developer Console to make your app available for download -around the world. Keep in mind, it can take several hours for your app to appear on Android -Market after you click <strong>Publish</strong> in the Developer Console.</p> +around the world. Keep in mind, it can take several hours for your app to appear on Google +Play after you click <strong>Publish</strong> in the Developer Console.</p> <h3>Controlling Distribution to Devices</h3> <p>If your application targets different device configurations, you can control which Android-powered -devices have access to your application on Android Market by -using Android Market filters. Filtering compares device configurations that you declare in your +devices have access to your application on Google Play by +using Google Play filters. Filtering compares device configurations that you declare in your app's manifest file to the configuration defined by a device. For example, if you declare the camera -filter in your manifest, only those devices that have a camera will see your app on Android -Market. Filters must be configured in your application's manifest file when you are <a +filter in your manifest, only those devices that have a camera will see your app on Google +Play. Filters must be configured in your application's manifest file when you are <a href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before -you upload your app to Android Market). For more information, see <a -href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> +you upload your app to Google Play). For more information, see <a +href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> <p>You can also use the multiple APK feature to distribute different {@code .apk} files under the same application listing and the same package name; however, you should use this option only as a last @@ -205,17 +205,17 @@ few cases, however, a single APK is unable to support all device configurations, resources make the APK file too big (greater than 50MB) or other technical challenges prevent a single APK from working on all devices. Although we encourage you to develop and publish a single APK that supports as many device configurations as possible, doing so is sometimes -not possible. To help you publish your application for as many devices as possible, Android Market -allows you to publish multiple APKs under the same application listing. Android Market then supplies +not possible. To help you publish your application for as many devices as possible, Google Play +allows you to publish multiple APKs under the same application listing. Google Play then supplies each APK to the appropriate devices based on configuration support you've declared in the manifest file of each APK. To use this feature, you need to build your separate {@code .apk} files when you are <a href="{@docRoot}guide/publishing/preparing.html">preparing your app for release</a> (that is, before -you upload your app to Android Market). For more information, see <a +you upload your app to Google Play). For more information, see <a href="{@docRoot}guide/market/publishing/multiple-apks.html">Multiple APK Support</a>.</p> -<h2 id="marketupgrade">Publishing Updates on Android Market</h2> +<h2 id="marketupgrade">Publishing Updates on Google Play</h2> -<p>At any time after publishing an application on Android Market, you can upload +<p>At any time after publishing an application on Google Play, you can upload and publish an update to the same application package. When you publish an update to an application, users who have already installed the application may receive a notification that an update is @@ -228,49 +228,49 @@ attributes in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><code><manifest></code></a> element of the manifest file. Also, the package name must be the same as the existing version and the {@code .apk} file must be signed with the same private key. If the package name and signing -certificate do <em>not</em> match those of the existing version, Market will +certificate do <em>not</em> match those of the existing version, Google Play will consider it a new application, publish it as such, and will not offer it to existing users as an update.</p> -<p>If you plan to publish your application on Android Market, you must make sure - that it meets the requirements listed below, which are enforced by the Market - server when you upload the application.</p> +<p>If you plan to publish your application on Google Play, you must make sure + that it meets the requirements listed below, which are enforced by Google Play + when you upload the application.</p> -<h2 id="marketLicensing">Using Android Market Licensing Service</h2> +<h2 id="marketLicensing">Using Google Play Licensing Service</h2> -<p>Android Market offers a licensing service that lets you enforce licensing -policies for paid applications that you publish through Android Market. With -Android Market Licensing, your applications can query Android Market at runtime +<p>Google Play offers a licensing service that lets you enforce licensing +policies for paid applications that you publish through Google Play. With +Google Play Licensing, your applications can query Google Play at runtime to obtain the licensing status for the current user, then allow or disallow further use of the application as appropriate. Using the service, you can apply a flexible licensing policy on an application-by-application basis—each application can enforce its licensing status in the way most appropriate for it. </p> -<p>Any application that you publish through Android Market can use the Android -Market Licensing Service. The service uses no dedicated framework APIs, so you can +<p>Any application that you publish through Google Play can use the Google +Play Licensing Service. The service uses no dedicated framework APIs, so you can add licensing to any application that uses a minimum API Level of 3 or higher.</p> -<p>For complete information about Android Market Licensing Service and how to +<p>For complete information about Google Play Licensing Service and how to use it in your application, read <a -href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a>.</p> +href="{@docRoot}guide/market/licensing/index.html">Application Licensing</a>.</p> -<h2 id="marketinappbilling">Using Android Market In-app Billing</h2> +<h2 id="marketinappbilling">Using Google Play In-app Billing</h2> -<p><a href="{@docRoot}guide/market/billing/billing_overview.html">Android Market In-app Billing</a> -is an Android Market service that lets you sell digital content in your applications. You can use +<p><a href="{@docRoot}guide/market/billing/billing_overview.html">Google Play In-app Billing</a> +is a Google Play service that lets you sell digital content in your applications. You can use the service to sell a wide range of content, including downloadable content such as media files or photos, and virtual content such as game levels or potions.</p> -<p>When you use Android Market's in-app billing service to sell an item, Android Market handles all +<p>When you use Google Play's in-app billing service to sell an item, Google Play handles all billing details so your application never has to directly process any financial transactions. -Android Market uses the same checkout service that is used for application purchases, so your users +Google Play uses the same checkout service that is used for application purchases, so your users experience a consistent and familiar purchase flow (see figure 1). Also, the transaction fee for in-app purchases is the same as the transaction fee for application purchases (30%).</p> -<p>Any application that you publish through Android Market can implement in-app billing. No special -account or registration is required other than an Android Market publisher account and a Google +<p>Any application that you publish through Google Play can implement in-app billing. No special +account or registration is required other than a Google Play publisher account and a Google Checkout Merchant account. Also, because the service uses no dedicated framework APIs, you can add in-app billing to any application that uses a minimum API level of 4 or higher.</p> @@ -282,58 +282,59 @@ also contains examples of the database, user interface, and business logic you m implement in-app billing. For more information about the in-app billing feature, see the <a href="{@docRoot}guide/market/billing/index.html">In-app Billing documentation</a>.</p> -<h2 id="marketintent">Linking to Your Apps on Android Market</h2> +<h2 id="marketintent">Linking to Your Apps on Google Play</h2> -<p>To help users discover your published applications, you can use two special Android Market URIs +<p>To help users discover your published applications, you can use two special Google Play URIs that direct users to your application's details page or perform a search for all of your published -applications in Android Market. You can use these URIs to create a button in your application or a +applications on Google Play. You can use these URIs to create a button in your application or a link on a web page that:</p> <ul> - <li>Opens your application's details page in the Android Market application or web site.</li> - <li>Searches for all your published applications in the Android Market application or web + <li>Opens your application's details page in the Google Play application or web site.</li> + <li>Searches for all your published applications in the Google Play application or web site.</li> </ul> -<p>You can launch the Android Market application or web site in the following ways:</p> +<p>You can launch the Google Play application or web site in the following ways:</p> <ul> <li>Initiate an {@link android.content.Intent} from your application that launches the -Android Market application on the user's device.</li> - <li>Provide a link on a web page that opens the Android Market web site (but will also -open the Android Market application if clicked from a device).</li> +Google Play application on the user's device.</li> + <li>Provide a link on a web page that opens the Google Play web site (but will also +open the Google Play application if clicked from a device).</li> </ul> <p>In both cases, whether you want to initiate the action from your application or from a web page, the URIs are quite similar. The only difference is the URI prefix.</p> -<p>To open the Android Market application from your application, the prefix for the intent's data +<p>To open the Google Play application from your application, the prefix for the intent's data URI is:</p> <p style="margin-left:2em"><code>market://</code></p> -<p>To open Android Market from your web site, the prefix for the link URI is:</p> +<p>To open Google Play store from your web site, the prefix for the link URI is:</p> -<p style="margin-left:2em"><code>http://market.android.com/</code></p> +<p style="margin-left:2em"><code>http://play.google.com/store/</code></p> <p>The following sections describe how to create a complete URI for each action.</p> -<p class="note"><strong>Note:</strong> If you create a link to open Android Market from your web -site and the user selects it from an Android-powered device, the device's Market application will -resolve the link so the user can use the Market application instead of opening the web -site. As such, you should always use {@code http://market.android.com/} URIs when creating a link on +<p class="note"><strong>Note:</strong> If you create a link to open Google Play from your web +site and the user selects it from an Android-powered device, the device's Google Play application will +resolve the link so the user can use the Google Play application on the device instead of opening the web +site. As such, you should always use {@code http://play.google.com/store/apps/...} URIs when +creating a link on a web page. When pointing to your apps from within your Android app, use the -{@code market://} URIs in an intent, so that the Market application always opens.</p> +{@code market://} URIs in an intent, so that the Google Play application always opens.</p> <h3 id="OpeningDetails">Opening an app's details page</h3> <p>As described above, you can open the details page for a specific application either on the -Android Market application or the Android Market web site. The details page allows the user to see +Google Play application or the Google Play web site. The details page allows the user to see the application description, screenshots, reviews and more, and choose to install it.</p> <p>The format for the URI that opens the details page is:</p> -<p style="margin-left:2em"><code><URI_prefix><b>details?id=</b><package_name></code></p> +<p style="margin-left:2em"><code><URI_prefix><b>apps/details?id=</b><package_name></code></p> <p>The <code><package_name></code> is a placeholder for the target application's fully-qualified package name, as declared in the <a @@ -341,26 +342,28 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a> attribute of the <a href="{@docRoot}guide/topics/manifest/manifest-element.html">{@code <manifest>}</a> element.</p> +<p>For example: <code>http://play.google.com/store/apps/details?id=com.example.myapp</code></p> + <h4>Opening the app details page from your Android app</h4> -<p>To open the Android Market details page from your application, +<p>To open the Google Play details page from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://details?id=<package_name></code></p> <p>For example, here's how you can create an intent and open an application's details page in -Android Market:</p> +Google Play:</p> <pre> Intent intent = new Intent(Intent.ACTION_VIEW); -intent.setData(Uri.parse("market://details?id=com.android.example")); +intent.setData(Uri.parse("market://details?id=com.example.android")); startActivity(intent); </pre> -<p>This will open the Android Market application on the device to view the {@code -com.android.example} application.</p> +<p>This will open the Google Play application on the device to view the {@code +com.example.android} application.</p> <h4>Opening the app details page from a web site</h4> @@ -369,32 +372,32 @@ com.android.example} application.</p> format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/details?id=<package_name></code> + <code>http://play.google.com/store/apps/details?id=<package_name></code> </p> -<p>For example, here's a link that opens an application's details page on Android Market:</p> +<p>For example, here's a link that opens an application's details page on Google Play:</p> <pre> -<a href="http://market.android.com/details?id=com.android.example">App Link</a> +<a href="http://play.google.com/store/apps/details?id=com.example.android">App Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site to view the -{@code com.android.example} application. When clicked from an Android-powered device, users are -given the option to use either their web browser or the Android Market application to view the +<p>When clicked from a desktop web browser, this opens the Google Play web site to view the +{@code com.example.android} application. When clicked from an Android-powered device, users are +given the option to use either their web browser or the Google Play application to view the application.</p> <h3 id="PerformingSearch">Performing a search</h3> -<p>To initiate a search in Android Market, the format for the URI is:</p> +<p>To initiate a search on Google Play, the format for the URI is:</p> <p style="margin-left:2em"> <code><URI_prefix><b>search?q=</b><query></code> </p> -<p>The <code><query></code> is a placeholder for the search query to execute in Android -Market. The query can be a raw text string or you can include a parameter that performs a search +<p>The <code><query></code> is a placeholder for the search query to execute in Google +Play. The query can be a raw text string or you can include a parameter that performs a search based on the publisher name:</p> <ul> @@ -410,14 +413,14 @@ by the publisher name: <h4>Searching from your Android app</h4> -<p>To initiate a search on Android Market from your application, create an intent with the +<p>To initiate a search on Google Play from your application, create an intent with the {@link android.content.Intent#ACTION_VIEW} action and include a data URI in this format:</p> <p style="margin-left:2em"><code>market://search?q=<query></code></p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's how you can initiate a search in the Android Market application, based on the +<p>For example, here's how you can initiate a search in the Google Play application, based on the publisher name:</p> <pre> @@ -426,46 +429,46 @@ intent.setData(Uri.parse("market://search?q=pub:Your Publisher Name")); startActivity(intent); </pre> -<p>This opens the Android Market application to perform the search. The search result shows all +<p>This opens the Google Play application to perform the search. The search result shows all applications published by the publisher that are compatible with the current device.</p> <h4>Searching from a web site</h4> -<p>To initiate a search on Android Market from your web site, create a link with a URI in this +<p>To initiate a search on Google Play from your web site, create a link with a URI in this format:</p> <p style="margin-left:2em"> - <code>http://market.android.com/search?q=<query></code> + <code>http://play.google.com/store/search?q=<query></code> </p> <p>The query may include the {@code pub:} parameter described above.</p> -<p>For example, here's a link that initiates a search on Android Market, based on the +<p>For example, here's a link that initiates a search on Google Play, based on the publisher name:</p> <pre> -<a href="http://market.android.com/search?q=pub:Your Publisher Name">Search Link</a> +<a href="http://play.google.com/store/search?q=pub:Your Publisher Name">Search Link</a> </pre> -<p>When clicked from a desktop web browser, this opens the Android Market web site and performs the +<p>When clicked from a desktop web browser, this opens the Google Play web site and performs the search. When clicked from an Android-powered device, users are given the option to use either their -web browser or the Android Market application to perform the search.</p> +web browser or the Google Play application to perform the search.</p> -<h3 id="BuildaButton">Build an Android Market button</h3> +<h3 id="BuildaButton">Build a Google Play button</h3> -<p>Use the following form to generate an "Available in Android Market" button that you can use on -your web site. Input either your application's package name or publisher name and the button will -take users to Android Market to either view your application's information or view a list of -your published apps. If users click the button while on an Android-powered device, the Android -Market application will respond to show users your application(s).</p> +<p>Use the following form to create a button for your web site that takes users to your application +on Google Play. Input either your application's package name or your publisher name and the button +will take users to Google Play to either view your application's information or view a list of your +published apps. If users click the button while on an Android-powered device, the Google Play +application will respond to show users your application(s).</p> -<p>This form offers four versions of the official "Available in Android Market" button at -recommended sizes. If you want to create a different size, you can download an EPS file for -the button images from the <a href="http://www.android.com/branding.html">Android Brand -Guidelines</a>.</p> +<p>This form offers two styles of the official brand badge each at recommended sizes. You can pick +between either "Get it on Google Play" or "Android app on Google Play." You should not modify the +badge images in any way. For more usage guidelines, +see the <a href="http://www.android.com/branding.html">Android Brand Guidelines</a>.</p> <style type="text/css"> @@ -507,33 +510,44 @@ div.button-row input { // variables for creating 'try it out' demo button var imagePath = "http://www.android.com/images/brand/" -var linkStart = "<a href=\"http://market.android.com/"; +var linkStart = "<a href=\"http://play.google.com/store/"; var imageStart = "\">\n" - + " <img src=\"" + imagePath; -var imageEnd = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrc = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEnd = ".png\" />\n</a>"; // variables for creating code snippet -var linkStartCode = "<a href=\"http://market.android.com/"; +var linkStartCode = "<a href=\"http://play.google.com/store/"; var imageStartCode = "\">\n" - + " <img src=\"" + imagePath; -var imageEndCode = ".png\"\n" - + " alt=\"Available in Android Market\" />\n</a>"; + + " <img alt=\""; + // leaves opening for the alt text value +var imageSrcCode = "\"\n src=\"" + imagePath; + // leaves opening for the image file name +var imageEndCode = ".png\" />\n</a>"; /** Generate the HTML snippet and demo based on form values */ function buildButton(form) { - if (form["package"].value != "com.android.example") { + var selectedValue = $('form input[type=radio]:checked').val(); + var altText = selectedValue.indexOf("get_it") != -1 ? "Get it on Google Play" : "Android app on Google Play"; + + if (form["package"].value != "com.example.android") { $("#preview").show(); - $("#snippet").show().html(linkStartCode + "details?id=" + form["package"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "details?id=" + form["package"].value - + imageStart + $('form input[type=radio]:checked').val() + imageEnd); + $("#snippet").show().html(linkStartCode + "apps/details?id=" + form["package"].value + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "apps/details?id=" + form["package"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else if (form["publisher"].value != "Example, Inc.") { $("#preview").show(); $("#snippet").show().html(linkStartCode + "search?q=pub:" + form["publisher"].value - + imageStartCode + $('form input[type=radio]:checked').val() + imageEndCode); - $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + imageStart + - $('form input[type=radio]:checked').val() + imageEnd); + + imageStartCode + altText + imageSrcCode + + selectedValue + imageEndCode); + $("#button-preview").html(linkStart + "search?q=pub:" + form["publisher"].value + + imageStart + altText + imageSrc + + selectedValue + imageEnd); } else { alert("Please enter your package name or publisher name"); } @@ -597,13 +611,13 @@ $(document).ready(function() { <form class="button-form"> <label class="block" for="package">Package name:</label> <input class="text" type="text" id="package" name="package" - value="com.android.example" - default="com.android.example" - onfocus="onInputFocus(this, 'com.android.example')" - onblur="onInputBlur(this, 'com.android.example')" + value="com.example.android" + default="com.example.android" + onfocus="onInputFocus(this, 'com.example.android')" + onblur="onInputBlur(this, 'com.example.android')" onkeyup="return onTextEntered(event, this.parentNode, this)"/> <a id="package-clear" style="display:none" href="#" - onclick="return clearLabel('package','com.android.example');">clear</a> + onclick="return clearLabel('package','com.example.android');">clear</a> <p style="clear:both;margin:0"> <em>or</em></p> <label class="block" style="margin-top:5px" for="publisher">Publisher name:</label> <input class="text" type="text" id="publisher" name="publisher" @@ -617,23 +631,23 @@ $(document).ready(function() { <br/><br/> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo1" id="ns" checked="checked" /> - <label for="ns"><img src="http://www.android.com/images/brand/45_avail_market_logo1.png" -alt="narrow and small logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_small" id="ns" checked="checked" /> + <label for="ns"><img src="http://www.android.com/images/brand/get_it_on_play_logo_small.png" +alt="Get it on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo1" id="nm" /> - <label for="nm"><img src="http://www.android.com/images/brand/60_avail_market_logo1.png" -alt="narrow and large logo" /></label> + <input type="radio" name="buttonStyle" value="get_it_on_play_logo_large" id="nm" /> + <label for="nm"><img src="http://www.android.com/images/brand/get_it_on_play_logo_large.png" +alt="Get it on Google Play (large)" /></label> </div> <div class="button-row"> - <input type="radio" name="buttonStyle" value="45_avail_market_logo2" id="ws" /> - <label for="ws"><img src="http://www.android.com/images/brand/45_avail_market_logo2.png" -alt="wide and small logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_small" id="ws" /> + <label for="ws"><img src="http://www.android.com/images/brand/android_app_on_play_logo_small.png" +alt="Android app on Google Play (small)" /></label> - <input type="radio" name="buttonStyle" value="60_avail_market_logo2" id="wm" /> - <label for="wm"><img src="http://www.android.com/images/brand/60_avail_market_logo2.png" -alt="wide and large logo" /></label> + <input type="radio" name="buttonStyle" value="android_app_on_play_logo_large" id="wm" /> + <label for="wm"><img src="http://www.android.com/images/brand/android_app_on_play_logo_large.png" +alt="Android app on Google Play (large)" /></label> </div> <input type="button" onclick="return buildButton(this.parentNode)" value="Build my button" @@ -643,7 +657,7 @@ style="padding:5px" /> <div id="preview" style="display:none"> <p>Copy and paste this HTML into your web site:</p> - <textarea id="snippet" cols="80" rows="4" onclick="this.select()" + <textarea id="snippet" cols="100" rows="5" onclick="this.select()" style="font-family:monospace;background-color:#efefef;padding:5px;display:none;margin-bottom:1em"> </textarea > @@ -658,7 +672,7 @@ style="font-family:monospace;background-color:#efefef;padding:5px;display:none;m <h3 id="UriSummary">Summary of URI formats</h3> -<p>The table below provides a summary of the URIs currently supported by the Android Market (both on +<p>The table below provides a summary of the URIs currently supported by the Google Play (both on the web and in the Android application), as discussed in the previous sections.</p> <table> @@ -670,19 +684,19 @@ the web and in the Android application), as discussed in the previous sections.< <tr> <td>Display the details screen for a specific application</td> -<td><code>http://market.android.com/details?id=<package_name></code> +<td><code>http://play.google.com/store/apps/details?id=<package_name></code> <td><code>market://details?id=<package_name></code></td> </tr> <tr> <td>Search for applications using a general string query.</td> -<td><code>http://market.android.com/search?q=<query></code></td> +<td><code>http://play.google.com/store/search?q=<query></code></td> <td><code>market://search?q=<query></code></td> </tr> <tr> <td>Search for applications by publisher name</td> -<td><nobr><code>http://market.android.com/search?q=pub:<publisher_name></code></nobr></td> +<td><nobr><code>http://play.google.com/store/search?q=pub:<publisher_name></code></nobr></td> <td><nobr><code>market://search?q=pub:<publisher_name></code></nobr></td> </tr> diff --git a/docs/html/guide/publishing/publishing_overview.jd b/docs/html/guide/publishing/publishing_overview.jd index 79199c5..6fb77e1 100755 --- a/docs/html/guide/publishing/publishing_overview.jd +++ b/docs/html/guide/publishing/publishing_overview.jd @@ -14,7 +14,7 @@ page.title=Publishing Overview <li><a href="#publishing-prepare">Preparing Your Application for Release</a></li> <li><a href="#publishing-release">Releasing Your Application to Users</a> <ol> - <li><a href="#publishing-market">Releasing on Android Market</a></li> + <li><a href="#publishing-market">Releasing on Google Play</a></li> <li><a href="#publishing-website">Releasing on your own website</a></li> <li><a href="#publishing-email">Releasing through email</a></li> </ol> @@ -23,7 +23,7 @@ page.title=Publishing Overview <ol> <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing for Release</a></li> - <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Android Market</a></li> + <li><a href="{@docRoot}guide/publishing/publishing.html">Publishing on Google Play</a></li> </ol> </div> </div> @@ -42,7 +42,7 @@ publish an Android application you perform two main tasks:</p> </li> </ul> -<p>Usually, you release your application through an application marketplace, such as Android Market. +<p>Usually, you release your application through an application marketplace, such as Google Play. However, you can also release applications by sending them directly to users or by letting users download them from your own website.</p> @@ -73,7 +73,7 @@ tasks:</p> <code>android:versionCode</code> and <code>android:versionName</code> attributes, which are located in the <a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> - element. You may also have to configure several other settings to meet Android Market + element. You may also have to configure several other settings to meet Google Play requirements or accomodate whatever method you're using to release your application.</p> </li> <li>Building and signing a release version of your application. @@ -114,27 +114,27 @@ application.</p> <h2 id="publishing-release">Releasing Your Application to Users</h2> <p>You can release your Android applications several ways. Usually, you release applications -through an application marketplace, such as Android Market, but you can also release applications -on your own website or by sending an application directly to a user. Android Market is the +through an application marketplace, such as Google Play, but you can also release applications +on your own website or by sending an application directly to a user. Google Play is the recommended marketplace for Android applications and is particularly useful if you want to distribute your applications to a large global audience. The other two release methods—server distribution and email distribution—are useful if you are releasing an application to a small group of users (for example, a work group in an enterprise environment), or if you do not want to make your application available to the general public.</p> -<h3 id="publishing-market">Releasing Your Applications on Android Market</h3> +<h3 id="publishing-market">Releasing Your Applications on Google Play</h3> -<p>Android Market is a robust publishing platform that helps you publicize, sell, and distribute +<p>Google Play is a robust publishing platform that helps you publicize, sell, and distribute your Android applications to users around the world. When you release your applications through -Android Market you have access to a suite of developer tools that let you analyze your sales, +Google Play you have access to a suite of developer tools that let you analyze your sales, identify market trends, and control who your applications are being distributed to. You also have access to several revenue-enhancing features that are not available anywhere else, such as <a href="{@docRoot}guide/market/billing/index.html">in-app billing</a> and <a -href="{@docRoot}guide/publishing/licensing.html">application licensing</a>. This rich array of tools -and features, coupled with numerous end-user community features, makes Android Market the premier +href="{@docRoot}guide/market/licensing.html">application licensing</a>. This rich array of tools +and features, coupled with numerous end-user community features, makes Google Play the premier marketplace for selling and buying Android applications.</p> -<p>Releasing your application on Android Market is a simple process that involves three basic +<p>Releasing your application on Google Play is a simple process that involves three basic steps:</p> <div class="figure" style="width:275px"> @@ -143,19 +143,19 @@ marketplace for selling and buying Android applications.</p> to be installed" /> <p class="img-caption"> <strong>Figure 2.</strong> The <strong>Unknown sources</strong> setting lets you install - applications that are not published on Android Market . + applications that are not published on Google Play . </p> </div> <ul> <li>Preparing promotional materials. - <p>To fully leverage the marketing and publicity capabilities of Android Market, you need to + <p>To fully leverage the marketing and publicity capabilities of Google Play, you need to create promotional materials for your application, such as screenshots, videos, graphics, and promotional text.</p> </li> <li>Configuring options and uploading assets. - <p>Android Market lets you target your application to a worldwide pool of users and devices. - By configuring various Android Market settings, you can choose the countries you want to + <p>Google Play lets you target your application to a worldwide pool of users and devices. + By configuring various Google Play settings, you can choose the countries you want to reach, the listing languages you want to use, and the price you want to charge in each country. You can also configure listing details such as the application type, category, and content rating. When you are done configuring options you can upload your promotional materials @@ -169,21 +169,21 @@ marketplace for selling and buying Android applications.</p> </li> </ul> -<p>For information about Android Market, see <a -href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Android Market</a>. This -topic provides an introduction to Android Market features and provides a step-by-step guide for -distributing your applications on Android Market.</p> +<p>For information about Google Play, see <a +href="{@docRoot}guide/publishing/publishing.html#market">Publishing on Google Play</a>. This +topic provides an introduction to Google Play features and provides a step-by-step guide for +distributing your applications on Google Play.</p> <h3 id="publishing-website">Releasing your application on your own website</h3> -<p>If you do not want to release your application on an application marketplace like Android Market, +<p>If you do not want to release your application on an application marketplace like Google Play, you can release your application by making it available for download on your own website or server. To do this, you must first prepare your application for release (that is, you must build it for release and sign it). Then all you need to do is host the release-ready application on your website and provide a download link for the application. When users browse to your website with their Android-powered devices and download your application, the Android system will automatically start installing the application on the device. However, the installation process will start automatically -only if the user has configured their device to allow the installation of non-Android Market +only if the user has configured their device to allow the installation of non-Google Play applications.</p> <div class="figure" style="width:275px"> @@ -197,7 +197,7 @@ applications.</p> </div> <p>By default, Android-powered devices allow users to install applications only if the applications -have been downloaded from Android Market. To allow the installation of applications from other +have been downloaded from Google Play. To allow the installation of applications from other sources, users need to enable the <strong>Unknown sources</strong> setting on their devices, and they need to make this configuration change before they download your application to their device (see figure 2).</p> @@ -208,7 +208,7 @@ applications from unknown sources.</p> <p>Although it is relatively easy to release your application on your own website, it can be inefficient and cumbersome. For example, if you want to monetize your application you will have to process and track all financial transactions yourself and you will not be able to use -Android Market's in-app billing feature to sell in-app products. In addition, you will not be +Google Play's in-app billing feature to sell in-app products. In addition, you will not be able to use the licensing feature to help prevent unauthorized installation and use of your application.</p> @@ -222,7 +222,7 @@ button in the email message (see figure 3). Users can install your application b button.</p> <p class="note"><strong>Note:</strong> The <strong>Install Now</strong> button appears only if a -user has configured their device to allow the installation of non-Android Market applications and +user has configured their device to allow the installation of non-Google Play applications and they open your email with the native Gmail application.</p> <p>Releasing applications through email is convenient if you are sending your application to diff --git a/docs/html/guide/publishing/versioning.jd b/docs/html/guide/publishing/versioning.jd index 79ebf96..da57e3e 100644 --- a/docs/html/guide/publishing/versioning.jd +++ b/docs/html/guide/publishing/versioning.jd @@ -25,7 +25,7 @@ page.title=Versioning Your Applications <ol> <li><a href="{@docRoot}guide/publishing/preparing.html">Preparing to Publish Your Application</a></li> -<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Android Market</a></li> +<li><a href="{@docRoot}guide/publishing/publishing.html#market">Publishing On Google Play</a></li> <li><a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a></li> </ol> diff --git a/docs/html/guide/topics/admin/device-admin.jd b/docs/html/guide/topics/admin/device-admin.jd index 820c3c0..4a325db 100644 --- a/docs/html/guide/topics/admin/device-admin.jd +++ b/docs/html/guide/topics/admin/device-admin.jd @@ -75,8 +75,8 @@ server. </li> not currently have an automated provisioning solution. Some of the ways a sysadmin might distribute the application to users are as follows: <ul> -<li>Android Market.</li> -<li>Enabling non-market installation.</li> +<li>Google Play.</li> +<li>Enabling installation from another store.</li> <li>Distributing the application through other means, such as email or websites.</li> </ul> diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd index 79dfd88..d91e422 100644 --- a/docs/html/guide/topics/data/backup.jd +++ b/docs/html/guide/topics/data/backup.jd @@ -892,8 +892,8 @@ href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr}</a>.</p> <li>Install your application on a suitable Android system image <ul> <li>If using the emulator, create and use an AVD with Android 2.2 (API Level 8).</li> - <li>If using a device, the device must be running Android 2.2 or greater and have Android -Market built in.</li> + <li>If using a device, the device must be running Android 2.2 or greater and have Google +Play built in.</li> </ul> </li> <li>Ensure that backup is enabled diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd index d1a3786..a86d905 100644 --- a/docs/html/guide/topics/fundamentals.jd +++ b/docs/html/guide/topics/fundamentals.jd @@ -392,13 +392,13 @@ same features and capabilities. In order to prevent your application from being that lack features needed by your application, it's important that you clearly define a profile for the types of devices your application supports by declaring device and software requirements in your manifest file. Most of these declarations are informational only and the system does not read -them, but external services such as Android Market do read them in order to provide filtering +them, but external services such as Google Play do read them in order to provide filtering for users when they search for applications from their device.</p> <p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an -Android version <em>lower</em> than 2.1 cannot install your application from Android Market.</p> +Android version <em>lower</em> than 2.1 cannot install your application from Google Play.</p> <p>However, you can also declare that your application uses the camera, but does not <em>require</em> it. In that case, your application must perform a check at runtime to determine @@ -458,12 +458,12 @@ element.</dd> </dl> <p>It's important that you declare all such requirements for your application, because, when you -distribute your application on Android Market, Market uses these declarations to filter which +distribute your application on Google Play, the store uses these declarations to filter which applications are available on each device. As such, your application should be available only to devices that meet all your application requirements.</p> -<p>For more information about how Android Market filters applications based on these (and other) -requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> +<p>For more information about how Google Play filters applications based on these (and other) +requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> document.</p> diff --git a/docs/html/guide/topics/fundamentals/activities.jd b/docs/html/guide/topics/fundamentals/activities.jd index 8736aa8..b79136c 100644 --- a/docs/html/guide/topics/fundamentals/activities.jd +++ b/docs/html/guide/topics/fundamentals/activities.jd @@ -62,7 +62,7 @@ is presented to the user when launching the application for the first time. Each activity can then start another activity in order to perform different actions. Each time a new activity starts, the previous activity is stopped, but the system preserves the activity in a stack (the "back stack"). When a new activity starts, it is pushed onto the back stack and -takes user focus. The back stack abides to the basic "last in, first out" queue mechanism, +takes user focus. The back stack abides to the basic "last in, first out" stack mechanism, so, when the user is done with the current activity and presses the <em>Back</em> button, it is popped from the stack (and destroyed) and the previous activity resumes. (The back stack is discussed more in the <a href="{@docRoot}guide/topics/fundamentals/tasks-and-back-stack.html">Tasks diff --git a/docs/html/guide/topics/fundamentals/fragments.jd b/docs/html/guide/topics/fundamentals/fragments.jd index 281cb9d..2a22394 100644 --- a/docs/html/guide/topics/fundamentals/fragments.jd +++ b/docs/html/guide/topics/fundamentals/fragments.jd @@ -129,7 +129,7 @@ handset design.</p> <p>For example—to continue with the news application example—the application can embed two fragments in <em>Activity A</em>, when running on a tablet-sized device. However, on a -handset-sized screen, there's not be enough room for both fragments, so <em>Activity A</em> includes +handset-sized screen, there's not enough room for both fragments, so <em>Activity A</em> includes only the fragment for the list of articles, and when the user selects an article, it starts <em>Activity B</em>, which includes the second fragment to read the article. Thus, the application supports both tablets and handsets by reusing fragments in different combinations, as illustrated in diff --git a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd index 465cf54..0880614 100644 --- a/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd +++ b/docs/html/guide/topics/fundamentals/tasks-and-back-stack.jd @@ -154,7 +154,7 @@ See the following section about <a href="#ActivityState">Activity state</a>.</p> <p>Because the activities in the back stack are never rearranged, if your application allows users to start a particular activity from more than one activity, a new instance of -that activity is created and popped onto the stack (rather than bringing any previous instance of +that activity is created and pushed onto the stack (rather than bringing any previous instance of the activity to the top). As such, one activity in your application might be instantiated multiple times (even from different tasks), as shown in figure 3. As such, if the user navigates backward using the <em>Back</em> button, each instance of the activity is revealed in the order they were @@ -291,7 +291,7 @@ B should associate with current task. If both activities define how Activity B should associate with a task, then Activity A's request (as defined in the intent) is honored over Activity B's request (as defined in its manifest).</p> -<p class="note"><strong>Note:</strong> Some the launch modes available in the manifest +<p class="note"><strong>Note:</strong> Some launch modes available for the manifest file are not available as flags for an intent and, likewise, some launch modes available as flags for an intent cannot be defined in the manifest.</p> diff --git a/docs/html/guide/topics/graphics/hardware-accel.jd b/docs/html/guide/topics/graphics/hardware-accel.jd index 39ccbf4..04fb564 100644 --- a/docs/html/guide/topics/graphics/hardware-accel.jd +++ b/docs/html/guide/topics/graphics/hardware-accel.jd @@ -42,19 +42,20 @@ parent.link=index.html <li><a href="{@docRoot}guide/topics/graphics/opengl.html">OpenGL with the Framework APIs</a></li> - <li><a href="{@docRoot}guide/topics/renderscript/index.html">RenderScript</a></li> + <li><a href="{@docRoot}guide/topics/renderscript/index.html">Renderscript</a></li> </ol> </div> </div> <p>Beginning in Android 3.0 (API level 11), the Android 2D rendering pipeline is designed to better support hardware acceleration. Hardware acceleration carries out all drawing operations - that are performed on a {@link android.view.View}'s canvas using the GPU.</p> + that are performed on a {@link android.view.View}'s canvas using the GPU. Because of the + increased resources required to enable hardware acceleration, your app will consume more RAM.</p> <p>The easiest way to enable hardware acceleration is to turn it on globally for your entire application. If your application uses only standard views and {@link android.graphics.drawable.Drawable}s, turning it on globally should not cause any adverse - effects. However, because hardware acceleration is not supported for all of the 2D drawing + drawing effects. However, because hardware acceleration is not supported for all of the 2D drawing operations, turning it on might affect some of your applications that use custom views or drawing calls. Problems usually manifest themselves as invisible elements, exceptions, or wrongly rendered pixels. To remedy this, Android gives you the option to enable or disable hardware diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd index 6a2a20f..a786d42 100644 --- a/docs/html/guide/topics/graphics/opengl.jd +++ b/docs/html/guide/topics/graphics/opengl.jd @@ -189,7 +189,7 @@ shown below. <uses-feature android:glEsVersion="0x00020000" android:required="true" /> </pre> - <p>Adding this declaration causes the Android Market to restrict your application from being + <p>Adding this declaration causes Google Play to restrict your application from being installed on devices that do not support OpenGL ES 2.0.</p> </li> <li><strong>Texture compression requirements</strong> - If your application uses texture @@ -200,9 +200,9 @@ formats, see <a href="#textures">Texture compression support</a>. <p>Declaring texture compression requirements in your manifest hides your application from users with devices that do not support at least one of your declared compression types. For more -information on how Android Market filtering works for texture compressions, see the <a +information on how Google Play filtering works for texture compressions, see the <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html#market-texture-filtering"> -Android Market and texture compression filtering</a> section of the {@code +Google Play and texture compression filtering</a> section of the {@code <supports-gl-texture>} documentation.</p> </li> </ul> @@ -470,7 +470,7 @@ the next section. <p class="note"><strong>Note:</strong> Once you decide which texture compression formats your application will support, make sure you declare them in your manifest using <a href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html"><supports-gl-texture> -</a>. Using this declaration enables filtering by external services such as Android Market, so that +</a>. Using this declaration enables filtering by external services such as Google Play, so that your app is installed only on devices that support the formats your app requires. For details, see <a href="{@docRoot}guide/topics/graphics/opengl.html#manifest">OpenGL manifest declarations</a>.</p> diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd index 5f98902..8a2e9cd 100644 --- a/docs/html/guide/topics/location/index.jd +++ b/docs/html/guide/topics/location/index.jd @@ -98,7 +98,7 @@ Google APIs add-on, visit</p> href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> <p>For your convenience, the Google APIs add-on is also available as a downloadable component from -the Android SDK and AVD Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK +the Android SDK Manager (see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>).</p> <p class="note"><strong>Note:</strong> In order to display Google Maps data in a diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index f44901b..9dc124b 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -307,7 +307,7 @@ attribute). <dd>Whether or not an existing instance of the activity should be shut down (finished) whenever the user again launches its task (chooses the task on the home screen) — "{@code true}" if it should be shut down, and "{@code false}" -if not. The default value is "{@code false}". +if not. The default value is "{@code false}". <p> If this attribute and @@ -321,13 +321,15 @@ activity is ignored. The activity is not re-parented, but destroyed. Activity — "{@code true}" if it should be enabled, and "{@code false}" if not. The default value is "{@code false}". + <p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is available to applications, to improve performance for many common 2D graphics operations. When the hardware-accelerated renderer is enabled, most operations in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. This results in smoother animations, smoother scrolling, and improved responsiveness overall, even for applications that do not explicitly make use -the framework's OpenGL libraries. </p> +the framework's OpenGL libraries. Because of the increased resources required to +enable hardware acceleration, your app will consume more RAM.</p> <p>Note that not all of the OpenGL 2D operations are accelerated. If you enable the hardware-accelerated renderer, test your application to ensure that it can @@ -587,9 +589,9 @@ Permissions</a>. </p></dd> <dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the activity should run. Normally, +<dd>The name of the process in which the activity should run. Normally, all components of an application run in the default process created for the -application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's +application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different default for all components. But each component can override the default, allowing you to spread your application across @@ -670,7 +672,7 @@ unspecified}" setting.</td> <p class="note"><strong>Note:</strong> When you declare one of the landscape or portrait values, it is considered a hard requirement for the orientation in which the activity runs. As such, -the value you declare enables filtering by services such as Android Market so your application is +the value you declare enables filtering by services such as Google Play so your application is available only to devices that support the orientation required by your activities. For example, if you declare either {@code "landscape"}, {@code "reverseLandscape"}, or {@code "sensorLandscape"}, then your application will be available only to devices that support @@ -679,7 +681,7 @@ your application requires either portrait or landscape orientation with the <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> element. For example, <code><uses-feature android:name="android.hardware.screen.portrait"/></code>. This is purely a filtering behavior -provided by Android Market (and other services that support it) and the platform itself does not +provided by Google Play (and other services that support it) and the platform itself does not control whether your app can be installed when a device supports only certain orientations.</p> </dd> @@ -706,7 +708,7 @@ activity started for the first time. A "{@code true}" setting ensures that the activity can be restarted in the absence of retained state. For example, the activity that displays the home screen uses this setting to make sure that it does not get removed if it -crashes for some reason. +crashes for some reason. </p></dd> <dt><a name="aff"></a>{@code android:taskAffinity}</dt> diff --git a/docs/html/guide/topics/manifest/compatible-screens-element.jd b/docs/html/guide/topics/manifest/compatible-screens-element.jd index 5c89869..a27c316 100644 --- a/docs/html/guide/topics/manifest/compatible-screens-element.jd +++ b/docs/html/guide/topics/manifest/compatible-screens-element.jd @@ -27,10 +27,10 @@ specifies a specific screen size-density combination with which the application <p>The Android system <em>does not</em> read the {@code <compatible-screens>} manifest element (neither at install-time nor at runtime). This element is informational only and may be used -by external services (such as Android Market) to better understand the application's compatibility +by external services (such as Google Play) to better understand the application's compatibility with specific screen configurations and enable filtering for users. Any screen configuration that is <em>not</em> declared in this element is a screen with which the application is <em>not</em> -compatible. Thus, external services (such as Android Market) should not provide the application to +compatible. Thus, external services (such as Google Play) should not provide the application to devices with such screens.</p> <p class="caution"><strong>Caution:</strong> Normally, <strong>you should not use this manifest @@ -48,14 +48,14 @@ should use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element only for <em>large</em> and <em>xlarge</em> screen devices, the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element allows you to declare that your application does not -support <em>small</em> and <em>normal</em> screen sizes. External services (such as Android -Market) will filter your application accordingly. You can also use the <a +support <em>small</em> and <em>normal</em> screen sizes. External services (such as Google +Play) will filter your application accordingly. You can also use the <a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code <supports-screens>}</a> element to declare whether the system should resize your application for different screen sizes.</p> - <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a> -document for more information about how Android Market filters applications using this and + <p>Also see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> +document for more information about how Google Play filters applications using this and other manifest elements.</p> </dd> @@ -138,5 +138,5 @@ entry looks like if your application is compatible with only small and normal sc <dt>see also:</dt> <dd><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></dd> -<dd><a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a></dd> +<dd><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></dd> </dl> diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd index d737a67..98968d7 100644 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ b/docs/html/guide/topics/manifest/manifest-element.jd @@ -37,7 +37,7 @@ parent.link=manifest-intro.html <dt>description:</dt> <dd>The root element of the AndroidManifest.xml file. It must contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element -and specify {@code xlmns:android} and {@code package} attributes.</dd> +and specify {@code xmlns:android} and {@code package} attributes.</dd> <dt>attributes:</dt> <dd> @@ -150,9 +150,9 @@ either internal or external storage through the system settings.</td> </tr> </table> -<p class="caution"><strong>Caution:</strong> If your application uses the Android Market's Copy - Protection feature, it cannot be installed to a device's SD card. However, if you use Android - Market's <a href="{@docRoot}guide/publishing/licensing.html">Application Licensing</a> instead, +<p class="caution"><strong>Caution:</strong> If your application uses Google Play's Copy + Protection feature, it cannot be installed to a device's SD card. However, if you use Google + Play's <a href="{@docRoot}guide/market/licensing.html">Application Licensing</a> instead, your application <em>can</em> be installed to internal or external storage, including SD cards.</p> <p class="note"><strong>Note:</strong> By default, your application will be installed on the diff --git a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd index 6c4a05a..ebdd0b1 100644 --- a/docs/html/guide/topics/manifest/supports-gl-texture-element.jd +++ b/docs/html/guide/topics/manifest/supports-gl-texture-element.jd @@ -18,20 +18,20 @@ parent.link=manifest-intro.html <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <code + <p style="color:#669999;padding-top:1em;">Google Play and <code style="color:#669999;"><supports-gl-texture></code> elements</p> - <p style="margin-top:1em;">Android Market filters applications according + <p style="margin-top:1em;">Google Play filters applications according to the texture compression formats that they support, to ensure that they can be installed only on devices that can handle their textures properly. Developers can use texture compression filtering as a way of targeting specific device types, based on GPU platform.</p> <p style="margin-top:1em;" class="caution">For important information about how - Android Market uses <code><supports-gl-texture></code> elements as - the basis for filtering, please read <a href="#market-texture-filtering">Android - Market and texture compression filtering</a>, below.</p> + Google Play uses <code><supports-gl-texture></code> elements as + the basis for filtering, please read <a href="#market-texture-filtering">Google + Play and texture compression filtering</a>, below.</p> </div> </div> @@ -57,7 +57,7 @@ texture compression formats, you can declare multiple <p>Declared <code><supports-gl-texture></code> elements are informational, meaning that the Android system itself does not examine the elements at install time to ensure matching support on the device. However, other services -(such as Android Market) or applications can check your application's +(such as Google Play) or applications can check your application's <code><supports-gl-texture></code> declarations as part of handling or interacting with your application. For this reason, it's very important that you declare all of the texture compression formats (from the list below) that @@ -141,20 +141,20 @@ and others.</td> <dt>see also:</dt> <dd> <ul> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> </ul> </dd> -<h2 id="market-texture-filtering">Android Market and texture compression filtering</h2> +<h2 id="market-texture-filtering">Google Play and texture compression filtering</h2> -<p>Android Market filters the applications that are visible to users, so that +<p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with -their devices. One of the ways Market filters applications is by texture +their devices. One of the ways it filters applications is by texture compression compatibility, giving you control over the availability of your application to various devices, based on the capabilities of their GPUs.</p> <p>To determine an application's texture compression compatibility with a given -user's device, Android Market compares:</p> +user's device, Google Play compares:</p> <ul> <li>Texture compression formats that are supported by the application — @@ -164,26 +164,26 @@ an application declares its supported texture compression formats in a device reports the formats it supports as read-only system properties.</li> </ul> -<p>Each time you upload an application to the Android Market Publisher Site, -Android Market scans the application's manifest file and looks for any +<p>Each time you upload an application to the Google Play publisher site, +Google Play scans the application's manifest file and looks for any <code><supports-gl-texture></code> elements. It extracts the format descriptors from the elements and stores them internally as metadata associated with the application <code>.apk</code> and the application version. </p> -<p>When a user searches or browses for applications on Android Market, +<p>When a user searches or browses for applications on Google Play, the service compares the texture compression formats supported by the application with those supported by the user's device. The comparison is based on the format descriptor strings and a match must be exact.</p> <p>If <em>any</em> of an application's supported texture compression formats is -also supported by the device, Android Market allows the user to see the +also supported by the device, Google Play allows the user to see the application and potentially download it. Otherwise, if none of the application's -formats is supported by the device, Android Market filters the application so +formats is supported by the device, Google Play filters the application so that it is not available for download. </p> <p>If an application does not declare any <code><supports-gl-texture></code> elements, -Android Market does not apply any filtering based on GL texture compression format.</p> +Google Play does not apply any filtering based on GL texture compression format.</p> </dl> diff --git a/docs/html/guide/topics/manifest/supports-screens-element.jd b/docs/html/guide/topics/manifest/supports-screens-element.jd index 81d6e27..ae14121 100644 --- a/docs/html/guide/topics/manifest/supports-screens-element.jd +++ b/docs/html/guide/topics/manifest/supports-screens-element.jd @@ -80,7 +80,7 @@ should not use it.</p> A small screen is defined as one with a smaller aspect ratio than the "normal" (traditional HVGA) screen. An application that does not support small screens <em>will not be available</em> for - small screen devices from external services (such as Android Market), because there is little + small screen devices from external services (such as Google Play), because there is little the platform can do to make such an application work on a smaller screen. This is {@code "true"} by default. </dd> @@ -156,8 +156,8 @@ smallest screen width qualifier</a> ({@code sw<N>dp}).</p> <p class="caution"><strong>Caution:</strong> The Android system does not pay attention to this attribute, so it does not affect how your application behaves at runtime. Instead, it is used -to enable filtering for your application on services such as Android Market. However, -<strong>Android Market currently does not support this attribute for filtering</strong> (on Android +to enable filtering for your application on services such as Google Play. However, +<strong>Google Play currently does not support this attribute for filtering</strong> (on Android 3.2), so you should continue using the other size attributes if your application does not support small screens.</p> diff --git a/docs/html/guide/topics/manifest/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 9f80638..5f0a501 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -9,7 +9,7 @@ parent.link=manifest-intro.html <h2>In this document</h2> <ol> - <li><a href="#market-feature-filtering">Android Market and Feature-Based Filtering</a> + <li><a href="#market-feature-filtering">Google Play and Feature-Based Filtering</a> <ol> <li><a href="#declared">Filtering based on explicitly declared features</a></li> <li><a href="#implicit">Filtering based on implicit features</a></li> @@ -45,26 +45,26 @@ href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <code style="color:#669999;"><uses-feature></code> elements</p> - <p style="margin-top:1em;">Android Market filters the applications that are visible to users, so + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play and <code style="color:#669999;"><uses-feature></code> elements</p> + <p style="margin-top:1em;">Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with their -devices. One of the ways Market filters applications is by feature compatibility.</p> +devices. One of the ways it filters applications is by feature compatibility.</p> -<p style="margin-top:1em;">To do this, Market checks the +<p style="margin-top:1em;">To do this, Google Play checks the <code><uses-feature></code> elements in each application's manifest, to -establish the app's feature needs. Market then shows or hides the application to +establish the app's feature needs. Google Play then shows or hides the application to each user, based on a comparison with the features available on the user's device. </p> <p style="margin-top:1em;">By specifying the features that your application requires, -you enable Android Market to present your application only to users whose +you enable Google Play to present your application only to users whose devices meet the application's feature requirements, rather than presenting it to all users. </p> <p style="margin-top:1em;" class="caution">For important information about how -Android Market uses features as the basis for filtering, please read <a -href="#market-feature-filtering">Android Market and Feature-Based Filtering</a>, +Google Play uses features as the basis for filtering, please read <a +href="#market-feature-filtering">Google Play and Feature-Based Filtering</a>, below.</p> </div> </div> @@ -106,7 +106,7 @@ application requires.</p> <p>Declared <code><uses-feature></code> elements are informational only, meaning that the Android system itself does not check for matching feature support on the device before installing an application. However, other services -(such as Android Market) or applications may check your application's +(such as Google Play) or applications may check your application's <code><uses-feature></code> declarations as part of handling or interacting with your application. For this reason, it's very important that you declare all of the features (from the list below) that your application uses. </p> @@ -207,22 +207,22 @@ can check at run-time whether a higher level of OpenGL ES is available.)</p> <li>{@link android.content.pm.FeatureInfo}</li> <li>{@link android.content.pm.ConfigurationInfo}</li> <li><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><code><uses-permission></code></a></li> - <li><a href="{@docRoot}guide/appendix/market-filters.html">Android Market Filters</a></li> + <li><a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a></li> </ul> </dd> </dl> -<h2 id="market-feature-filtering">Android Market and Feature-Based Filtering</h2> +<h2 id="market-feature-filtering">Google Play and Feature-Based Filtering</h2> -<p>Android Market filters the applications that are visible to users, so that +<p>Google Play filters the applications that are visible to users, so that users can see and download only those applications that are compatible with -their devices. One of the ways Market filters applications is by feature +their devices. One of the ways it filters applications is by feature compatibility.</p> <p>To determine an application's feature compatibility with a given user's -device, the Android Market service compares:</p> +device, Google Play compares:</p> <ul> <li>Features required by the application — an application declares features in @@ -238,14 +238,14 @@ are listed in the <a href="#features-reference">Features Reference</a> tables at the bottom of this document, and in the class documentation for {@link android.content.pm.PackageManager}.</p> -<p>When the user launches the Market application, the application queries the +<p>When the user launches Google Play, the application queries the Package Manager for the list of features available on the device by calling {@link android.content.pm.PackageManager#getSystemAvailableFeatures()}. The -Market application then passes the features list up to the Android Market -service when establishing the session for the user.</p> +Store application then passes the features list up to Google Play +when establishing the session for the user.</p> -<p>Each time you upload an application to the Android Market Publisher Site, -Android Market scans the application's manifest file. It looks for +<p>Each time you upload an application to the Google Play publisher site, +Google Play scans the application's manifest file. It looks for <code><uses-feature></code> elements and evaluates them in combination with other elements, in some cases, such as <code><uses-sdk></code> and <code><uses-permission></code> elements. After establishing the @@ -253,17 +253,17 @@ application's set of required features, it stores that list internally as metadata associated with the application <code>.apk</code> and the application version. </p> -<p>When a user searches or browses for applications using the Android Market +<p>When a user searches or browses for applications using the Google Play application, the service compares the features needed by each application with the features available on the user's device. If all of an application's required -features are present on the device, Android Market allows the user to see the +features are present on the device, Google Play allows the user to see the application and potentially download it. If any required feature is not -supported by the device, Android Market filters the application so that it is +supported by the device, Google Play filters the application so that it is not visible to the user and not available for download. </p> <p>Because the features you declare in <code><uses-feature></code> -elements directly affect how Android Market filters your application, it's -important to understand how Android Market evaluates the application's manifest +elements directly affect how Google Play filters your application, it's +important to understand how Google Play evaluates the application's manifest and establishes the set of required features. The sections below provide more information. </p> @@ -277,35 +277,35 @@ application absolutely requires the feature and cannot function properly without it (<code>"true"</code>), or whether the application prefers to use the feature if available, but is designed to run without it (<code>"false"</code>).</p> -<p>Android Market handles explicitly declared features in this way: </p> +<p>Google Play handles explicitly declared features in this way: </p> <ul> -<li>If a feature is explicitly declared as being required, Android Market adds +<li>If a feature is explicitly declared as being required, Google Play adds the feature to the list of required features for the application. It then filters the application from users on devices that do not provide that feature. For example: <pre><uses-feature android:name="android.hardware.camera" android:required="true" /></pre></li> -<li>If a feature is explicitly declared as <em>not</em> being required, Android -Market <em>does not</em> add the feature to the list of required features. For +<li>If a feature is explicitly declared as <em>not</em> being required, Google +Play <em>does not</em> add the feature to the list of required features. For that reason, an explicitly declared non-required feature is never considered when filtering the application. Even if the device does not provide the declared -feature, Android Market will still consider the application compatible with the +feature, Google Play will still consider the application compatible with the device and will show it to the user, unless other filtering rules apply. For example: <pre><uses-feature android:name="android.hardware.camera" android:required="false" /></pre></li> <li>If a feature is explicitly declared, but without an -<code>android:required</code> attribute, Android Market assumes that the feature +<code>android:required</code> attribute, Google Play assumes that the feature is required and sets up filtering on it. </li> </ul> <p>In general, if your application is designed to run on Android 1.6 and earlier versions, the <code>android:required</code> attribute is not available in the -API and Android Market assumes that any and all +API and Google Play assumes that any and all <code><uses-feature></code> declarations are required. </p> <p class="note"><strong>Note:</strong> By declaring a feature explicitly and including an <code>android:required="false"</code> attribute, you can -effectively disable all filtering on Android Market for the specified feature. +effectively disable all filtering on Google Play for the specified feature. </p> @@ -317,7 +317,7 @@ function properly, but which is <em>not</em> declared in a speaking, every application should <em>always</em> declare all features that it uses or requires, so the absence of a declaration for a feature used by an application should be considered an error. However, as a safeguard for users and -developers, Android Market looks for implicit features in each application and +developers, Google Play looks for implicit features in each application and sets up filters for those features, just as it would do for an explicitly declared feature. </p> @@ -337,25 +337,25 @@ element name or an unrecognized string value for the </li> </ul> -<p>To account for the cases above, Android Market attempts to discover an +<p>To account for the cases above, Google Play attempts to discover an application's implied feature requirements by examining <em>other elements</em> declared in the manifest file, specifically, <code><uses-permission></code> elements.</p> -<p>If an application requests hardware-related permissions, Android Market +<p>If an application requests hardware-related permissions, Google Play <em>assumes that the application uses the underlying hardware features and therefore requires those features</em>, even though there might be no corresponding to <code><uses-feature></code> declarations. For such -permissions, Android Market adds the underlying hardware features to the +permissions, Google Play adds the underlying hardware features to the metadata that it stores for the application and sets up filters for them.</p> <p>For example, if an application requests the <code>CAMERA</code> permission but does not declare a <code><uses-feature></code> element for -<code>android.hardware.camera</code>, Android Market considers that the +<code>android.hardware.camera</code>, Google Play considers that the application requires a camera and should not be shown to users whose devices do not offer a camera.</p> -<p>If you don't want Android Market to filter based on a specific implied +<p>If you don't want Google Play to filter based on a specific implied feature, you can disable that behavior. To do so, declare the feature explicitly in a <code><uses-feature></code> element and include an <code>android:required="false"</code> attribute. For example, to disable @@ -366,30 +366,30 @@ the feature as shown below.</p> <p class="caution">It's important to understand that the permissions that you request in <code><uses-permission></code> elements can directly affect how -Android Market filters your application. The reference section <a +Google Play filters your application. The reference section <a href="#permissions">Permissions that Imply Feature Requirements</a>, below, lists the full set of permissions that imply feature requirements and therefore trigger filtering.</p> <h3 id="bt-permission-handling">Special handling for Bluetooth feature</h3> -<p>Android Market applies slightly different rules than described above, when +<p>Google Play applies slightly different rules than described above, when determining filtering for Bluetooth.</p> <p>If an application declares a Bluetooth permission in a <code><uses-permission></code> element, but does not explicitly declare -the Bluetooth feature in a <code><uses-feature></code> element, Android -Market checks the version(s) of the Android platform on which the application is +the Bluetooth feature in a <code><uses-feature></code> element, Google +Play checks the version(s) of the Android platform on which the application is designed to run, as specified in the <code><uses-sdk></code> element. </p> -<p>As shown in the table below, Android Market enables filtering for the +<p>As shown in the table below, Google Play enables filtering for the Bluetooth feature only if the application declares its lowest or targeted -platform as Android 2.0 (API level 5) or higher. However, note that Android -market applies the normal rules for filtering when the application explicitly +platform as Android 2.0 (API level 5) or higher. However, note that Google +Play applies the normal rules for filtering when the application explicitly declares the Bluetooth feature in a <code><uses-feature></code> element. </p> -<p class="caption"><strong>Table 1.</strong> How Android Market determines the +<p class="caption"><strong>Table 1.</strong> How Google Play determines the Bluetooth feature requirement for an application that requests a Bluetooth permission but does not declare the Bluetooth feature in a <code><uses-feature></code> element.</p> @@ -403,14 +403,14 @@ permission but does not declare the Bluetooth feature in a <tr> <td><nobr><=4 (or uses-sdk is not declared)</nobr></td> <td><=4</td> -<td>Android Market <em>will not</em> filter the application from any devices +<td>Google Play <em>will not</em> filter the application from any devices based on their reported support for the <code>android.hardware.bluetooth</code> feature.</td> </tr> <tr> <td><=4</td> <td>>=5</td> -<td rowspan="2">Android Market filters the application from any devices that +<td rowspan="2">Google Play filters the application from any devices that do not support the <code>android.hardware.bluetooth</code> feature (including older releases).</td> </tr> @@ -421,13 +421,13 @@ older releases).</td> </table> <p>The examples below illustrate the different filtering effects, based on how -Android Market handles the Bluetooth feature. </p> +Google Play handles the Bluetooth feature. </p> <dl> <dt>In first example, an application that is designed to run on older API levels declares a Bluetooth permission, but does not declare the Bluetooth feature in a <code><uses-feature></code> element.</dt> -<dd><em>Result:</em> Android Market does not filter the application from any device.</dd> +<dd><em>Result:</em> Google Play does not filter the application from any device.</dd> </dl> <pre><manifest ...> @@ -439,7 +439,7 @@ declares a Bluetooth permission, but does not declare the Bluetooth feature in a <dl> <dt>In the second example, below, the same application also declares a target API level of "5". </dt> -<dd><em>Result:</em> Android Market now assumes that the feature is required and +<dd><em>Result:</em> Google Play now assumes that the feature is required and will filter the application from all devices that do not report Bluetooth support, including devices running older versions of the platform. </dd> </dl> @@ -465,7 +465,7 @@ including devices running older versions of the platform. </dd> <dl> <dt>Finally, in the case below, the same application adds an <code>android:required="false"</code> attribute.</dt> -<dd><em>Result:</em> Android Market disables filtering based on Bluetooth +<dd><em>Result:</em> Google Play disables filtering based on Bluetooth feature support, for all devices.</dd> </dl> @@ -481,10 +481,10 @@ feature support, for all devices.</dd> <h3 id="testing">Testing the features required by your application</h3> <p>You can use the <code>aapt</code> tool, included in the Android SDK, to -determine how Android Market will filter your application, based on its declared +determine how Google Play will filter your application, based on its declared features and permissions. To do so, run <code>aapt</code> with the <code>dump badging</code> command. This causes <code>aapt</code> to parse your -application's manifest and apply the same rules as used by Android Market to +application's manifest and apply the same rules as used by Google Play to determine the features that your application requires. </p> <p>To use the tool, follow these steps: </p> @@ -501,7 +501,7 @@ If you are using SDK Tools r8 or higher, you can find <code>aapt</code> in the <p class="note"><strong>Note:</strong> You must use the version of <code>aapt</code> that is provided for the latest Platform-Tools component available. If you do not have the latest Platform-Tools component, download it using the <a -href="{@docRoot}sdk/adding-components.html">Android SDK and AVD Manager</a>. +href="{@docRoot}sdk/adding-components.html">Android SDK Manager</a>. </p></li> <li>Run <code>aapt</code> using this syntax: </li> </ol> @@ -529,7 +529,7 @@ densities: '160' <h2 id=features-reference>Features Reference</h2> <p>The tables below provide reference information about hardware and software -features and the permissions that can imply them on Android Market. </p> +features and the permissions that can imply them on Google Play. </p> <h3 id="hw-features">Hardware features</h3> @@ -873,12 +873,12 @@ level 5). Because of this, some apps were able to use the API before they had the ability to declare that they require the API via the <code><uses-feature></code> system. </p> -<p>To prevent those apps from being made available unintentionally, Android -Market assumes that certain hardware-related permissions indicate that the +<p>To prevent those apps from being made available unintentionally, Google +Play assumes that certain hardware-related permissions indicate that the underlying hardware features are required by default. For instance, applications that use Bluetooth must request the <code>BLUETOOTH</code> permission in a -<code><uses-permission></code> element — for legacy apps, Android -Market assumes that the permission declaration means that the underlying +<code><uses-permission></code> element — for legacy apps, Google +Play assumes that the permission declaration means that the underlying <code>android.hardware.bluetooth</code> feature is required by the application and sets up filtering based on that feature. </p> diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd index d94ad9f..2f8eb50 100644 --- a/docs/html/guide/topics/manifest/uses-library-element.jd +++ b/docs/html/guide/topics/manifest/uses-library-element.jd @@ -33,7 +33,7 @@ parent.link=manifest-intro.html </p> <p> This element also affects the installation of the application on a particular device and - the availability of the application in Android Market: + the availability of the application on Google Play: </p> <dl> <dt><em>Installation</em></dt> @@ -42,11 +42,11 @@ parent.link=manifest-intro.html {@code true}, the {@link android.content.pm.PackageManager} framework won't let the user install the application unless the library is present on the user's device. </dd> - <dt><em>Market</em></dt> + <dt><em>Google Play</em></dt> <dd> - Android Market filters applications based on the libraries installed on the + Google Play filters applications based on the libraries installed on the user's device. For more information about filtering, see the topic - <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>. + <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>. </dd> </dl> <p> diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd index 967fc5a..6c71fb4 100644 --- a/docs/html/guide/topics/manifest/uses-permission-element.jd +++ b/docs/html/guide/topics/manifest/uses-permission-element.jd @@ -8,21 +8,21 @@ parent.link=manifest-intro.html <div class="sidebox-wrapper"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;"><code style="color:#669999;"><uses-permission></code> and filtering on Android Market. </p> + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;"><code style="color:#669999;"><uses-permission></code> and filtering on Google Play. </p> <p style="margin-top:1em;">In some cases, the permissions that you request through <code><uses-permission></code> can affect how -your application is filtered by Android Market.</p> +your application is filtered by Google Play.</p> <p style="margin-top:1em;">If you request a hardware-related permission — -<code>CAMERA</code>, for example — Android Market assumes that your +<code>CAMERA</code>, for example — Google Play assumes that your application requires the underlying hardware feature and filters the application from devices that do not offer it.</p> <p style="margin-top:1em;">To control filtering, always explicitly declare hardware features in <code><uses-feature></code> elements, rather than -relying on Android Market to "discover" the requirements in +relying on Google Play to "discover" the requirements in <code><uses-permission></code> elements. Then, if you want to disable filtering for a particular feature, you can add a <code>android:required="false"</code> attribute to the diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd index 99c91f6..8fa39d1 100644 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ b/docs/html/guide/topics/manifest/uses-sdk-element.jd @@ -33,16 +33,16 @@ major version or the sum of the major and minor versions).</p> <div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;"> <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png"> <div id="qv-sub-rule"> - <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;"> - <p style="color:#669999;">Android Market and <uses-sdk> attributes</p> - <p>Android Market filters the applications that are visible to users, so + <img src="{@docRoot}assets/images/icon_play.png" style="float:left;margin:0;padding:0;"> + <p style="color:#669999;padding-top:1em;">Google Play and <uses-sdk> attributes</p> + <p style="padding-top:1em;">Google Play filters the applications that are visible to users, so that users can only see and download applications that are compatible with their -devices. One of the ways Market filters applications is by Android -version-compatibility. To do this, Market checks the <code><uses-sdk></code> +devices. One of the ways it filters applications is by Android +version-compatibility. To do this, Google Play checks the <code><uses-sdk></code> attributes in each application's manifest to establish its version-compatibility range, then shows or hides the application based on a comparison with the API Level of the user's Android system version. For more information, see <a -href="{@docRoot}guide/appendix/market-filters.html">Market Filters</a>.</p> +href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a>.</p> </div> </div> @@ -114,7 +114,7 @@ the corresponding platform version.</p> updates, consider the following example: </p> <p>An application declaring <code>maxSdkVersion="5"</code> in its - manifest is published on Android Market. A user whose device is running Android + manifest is published on Google Play. A user whose device is running Android 1.6 (API Level 4) downloads and installs the app. After a few weeks, the user receives an over-the-air system update to Android 2.0 (API Level 5). After the update is installed, the system checks the application's @@ -143,7 +143,7 @@ the corresponding platform version.</p> <div class="special">Future versions of Android (beyond Android 2.0.1) will no longer check or enforce the <code>maxSdkVersion</code> attribute during -installation or re-validation. Android Market will continue to use the attribute +installation or re-validation. Google Play will continue to use the attribute as a filter, however, when presenting users with applications available for download. </div> </dd> diff --git a/docs/html/guide/topics/media/camera.jd b/docs/html/guide/topics/media/camera.jd index 4e928b3..7d72491 100644 --- a/docs/html/guide/topics/media/camera.jd +++ b/docs/html/guide/topics/media/camera.jd @@ -131,11 +131,11 @@ for example: <p>For a list of camera features, see the manifest <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#hw-features">Features Reference</a>.</p> - <p>Adding camera features to your manifest causes Android Market to prevent your application from + <p>Adding camera features to your manifest causes Google Play to prevent your application from being installed to devices that do not include a camera or do not support the camera features you -specify. For more information about using feature-based filtering with Android Market, see <a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html#market-feature-filtering">Android -Market and Feature-Based Filtering</a>.</p> +specify. For more information about using feature-based filtering with Google Play, see <a +href="{@docRoot}guide/topics/manifest/uses-feature-element.html#market-feature-filtering">Google +Play and Feature-Based Filtering</a>.</p> <p>If your application <em>can use</em> a camera or camera feature for proper operation, but does not <em>require</em> it, you should specify this in the manifest by including the {@code android:required} attribute, and setting it to {@code false}:</p> @@ -442,7 +442,7 @@ use or does not exist will cause your application to be shut down by the system. the first, back-facing camera on a device with more than one camera.</p> <h3 id="check-camera-features">Checking camera features</h3> -<p>Once you obtain access to a camera, you can get further information about its capabilties using +<p>Once you obtain access to a camera, you can get further information about its capabilities using the {@link android.hardware.Camera#getParameters() Camera.getParameters()} method and checking the returned {@link android.hardware.Camera.Parameters} object for supported capabilities. When using API Level 9 or higher, use the {@link android.hardware.Camera#getCameraInfo(int, @@ -677,8 +677,8 @@ button {@link android.view.View.OnClickListener}.</p> <pre> // Add a listener to the Capture button Button captureButton = (Button) findViewById(id.button_capture); - captureButton.setOnClickListener( - new View.OnClickListener() { +captureButton.setOnClickListener( + new View.OnClickListener() { @Override public void onClick(View v) { // get an image from the camera @@ -1260,7 +1260,7 @@ supported.</p> <p>If your application requires certain camera features in order to function properly, you can require them through additions to your application manifest. When you declare the use of specific -camera features, such as flash and auto-focus, the Android Market restricts your application from +camera features, such as flash and auto-focus, Google Play restricts your application from being installed on devices which do not support these features. For a list of camera features that can be declared in your app manifest, see the manifest <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html#hw-features"> Features diff --git a/docs/html/guide/topics/network/sip.jd b/docs/html/guide/topics/network/sip.jd index 276adb6..600da78 100644 --- a/docs/html/guide/topics/network/sip.jd +++ b/docs/html/guide/topics/network/sip.jd @@ -147,7 +147,7 @@ href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a </ul> <p>To control how your application is filtered from devices that do not support -SIP (for example, in Android Market), add the following to your application's +SIP (for example, on Google Play), add the following to your application's manifest:</p> <ul> diff --git a/docs/html/guide/topics/nfc/nfc.jd b/docs/html/guide/topics/nfc/nfc.jd index 83873c3..834656a 100644 --- a/docs/html/guide/topics/nfc/nfc.jd +++ b/docs/html/guide/topics/nfc/nfc.jd @@ -318,8 +318,8 @@ other two intents, giving the user a better experience.</p> </pre> </li> - <li>The <code>uses-feature</code> element so that your application shows up in the Android -Market only for devices that have NFC hardware: + <li>The <code>uses-feature</code> element so that your application shows up in Google +Play only for devices that have NFC hardware: <pre> <uses-feature android:name="android.hardware.nfc" android:required="true" /> </pre> @@ -660,7 +660,7 @@ certainty that your application is started when an NFC tag is scanned. An AAR ha of an application embedded inside an NDEF record. You can add an AAR to any NDEF record of your NDEF message, because Android searches the entire NDEF message for AARs. If it finds an AAR, it starts the application based on the package name inside the AAR. If the application is not present on the device, -Android Market is launched to download the application.</p> +Google Play is launched to download the application.</p> <p>AARs are useful if you want to prevent other applications from filtering for the same intent and potentially handling specific tags that you have deployed. AARs are only supported at the @@ -678,7 +678,7 @@ the intent also matches the AAR, start the Activity.</li> <li>If the Activity that filters for the intent does not match the AAR, if multiple Activities can handle the intent, or if no Activity handles the intent, start the application specified by the AAR.</li> - <li>If no application can start with the AAR, go to the Android Market to download the + <li>If no application can start with the AAR, go to Google Play to download the application based on the AAR.</li> </ol> @@ -897,7 +897,7 @@ public class Beam extends Activity implements CreateNdefMessageCallback { <p>Note that this code comments out an AAR, which you can remove. If you enable the AAR, the application specified in the AAR always receives the Android Beam message. If the application is not -present, the Android Market is started to download the application. Therefore, the following intent +present, Google Play launches to download the application. Therefore, the following intent filter is not technically necessary for Android 4.0 devices or later if the AAR is used: </p> diff --git a/docs/html/guide/topics/providers/content-provider-basics.jd b/docs/html/guide/topics/providers/content-provider-basics.jd index 40b5c3f..de89568 100644 --- a/docs/html/guide/topics/providers/content-provider-basics.jd +++ b/docs/html/guide/topics/providers/content-provider-basics.jd @@ -123,7 +123,7 @@ page.title=Content Provider Basics <!-- Intro paragraphs --> <p> - A content provider manages access to a central repository of data. The provider and + A content provider manages access to a central repository of data. A provider is part of an Android application, which often provides its own UI for working with the data. However, content providers are primarily intended to be used by other applications, which access the provider using a provider client object. Together, providers @@ -569,7 +569,7 @@ selectionArgs[0] = mUserInput; </pre> <p> A selection clause that uses <code>?</code> as a replaceable parameter and an array of - selection arguments array are preferred way to specify a selection, even the provider isn't + selection arguments array are preferred way to specify a selection, even if the provider isn't based on an SQL database. </p> <!-- Displaying the results --> diff --git a/docs/html/guide/topics/renderscript/graphics.jd b/docs/html/guide/topics/renderscript/graphics.jd index 1c6d0de..462a990 100644 --- a/docs/html/guide/topics/renderscript/graphics.jd +++ b/docs/html/guide/topics/renderscript/graphics.jd @@ -142,7 +142,7 @@ href="{@docRoot}resources/samples/RenderScript/MiscSamples/index.html">Misc Samp <p class="note"><strong>Note:</strong> The Renderscript runtime makes its best effort to refresh the frame at the specified rate. For example, if you are creating a live wallpaper - and set the return value to 20, the Renderscript runtime renders the wallpaper at 20fps if it has just + and set the return value to 20, the Renderscript runtime renders the wallpaper at 50fps if it has just enough or more resources to do so. It renders as fast as it can if not enough resources are available.</p> @@ -570,7 +570,7 @@ point if this is your first time using Renderscript.</p> vertex 0, 1, and 2 (the vertices are drawn counter-clockwise).</p> <pre> int float2VtxSize = 2; -Mesh.TriangleMeshBuilder triangle = new Mesh.TriangleMeshBuilder(renderscriptGL, +Mesh.TriangleMeshBuilder triangles = new Mesh.TriangleMeshBuilder(renderscriptGL, float2VtxSize, Mesh.TriangleMeshBuilder.COLOR); triangles.addVertex(300.f, 300.f); triangles.addVertex(150.f, 450.f); diff --git a/docs/html/guide/topics/renderscript/index.jd b/docs/html/guide/topics/renderscript/index.jd index a0e8876..24b9750 100644 --- a/docs/html/guide/topics/renderscript/index.jd +++ b/docs/html/guide/topics/renderscript/index.jd @@ -231,7 +231,8 @@ would block until the value was returned.</p> <p> If you want the Renderscript code to send a value back to the Android framework, use the -<code>rsSendToClient()</code> function. +<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> +function. </p> <h3 id="var">Variables</h3> @@ -256,53 +257,6 @@ public long get_unsignedInteger(){ } </pre> - <h3 id="pointer">Pointers</h3> - <p>Pointers are reflected into the script class itself, located in -<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You -can declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a -<code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the -following pointers to a <code>struct</code> and <code>int32_t</code></p> - -<pre> -typedef struct Point { - float2 point; -} Point_t; - -Point_t *touchPoints; -int32_t *intPointer; -</pre> - <p>then the following code is generated in:</p> - - <pre> -private ScriptField_Point mExportVar_touchPoints; -public void bind_touchPoints(ScriptField_Point v) { - mExportVar_touchPoints = v; - if (v == null) bindAllocation(null, mExportVarIdx_touchPoints); - else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints); - } - - public ScriptField_Point get_touchPoints() { - return mExportVar_touchPoints; - } - - private Allocation mExportVar_intPointer; - public void bind_intPointer(Allocation v) { - mExportVar_intPointer = v; - if (v == null) bindAllocation(null, mExportVarIdx_intPointer); - else bindAllocation(v, mExportVarIdx_intPointer); - } - - public Allocation get_intPointer() { - return mExportVar_intPointer; - } - </pre> - -<p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> -(instead of a <code>set()</code> method) is generated. This method allows you to bind the memory -that is allocated in the Android VM to the Renderscript runtime (you cannot allocate -memory in your <code>.rs</code> file). For more information, see <a href="#memory">Working -with Allocated Memory</a>. -</p> <h3 id="struct">Structs</h3> <p>Structs are reflected into their own classes, located in @@ -311,7 +265,8 @@ with Allocated Memory</a>. specified number of <code>struct</code>s. For example, if you declare the following struct:</p> <pre> typedef struct Point { -float2 point; + float2 position; + float size; } Point_t; </pre> @@ -478,7 +433,8 @@ in memory. Each <code>struct</code>'s class defines the following methods and co </pre> <p>If you modify the memory in one memory space and want to push the updates to the rest of - the memory spaces, call <code>rsgAllocationSyncAll()</code> in your Renderscript code to + the memory spaces, call <a href="{@docRoot}reference/renderscript/rs__graphics_8rsh.html"> + <code>rsgAllocationSyncAll()</code></a> in your Renderscript code to synchronize the memory.</p> </li> @@ -511,6 +467,56 @@ Renderscript runtime. When you call a set accessor method on a member, there is properties that are not yet synchronized.</li> </ul> + <h3 id="pointer">Pointers</h3> + <p>Pointers are reflected into the script class itself, located in +<code>project_root/gen/package/name/ScriptC_renderscript_filename</code>. You +can declare pointers to a <code>struct</code> or any of the supported Renderscript types, but a +<code>struct</code> cannot contain pointers or nested arrays. For example, if you declare the +following pointers to a <code>struct</code> and <code>int32_t</code></p> + +<pre> +typedef struct Point { + float2 position; + float size; +} Point_t; + +Point_t *touchPoints; +int32_t *intPointer; +</pre> + <p>then the following code is generated in:</p> + +<pre> +private ScriptField_Point mExportVar_touchPoints; +public void bind_touchPoints(ScriptField_Point v) { + mExportVar_touchPoints = v; + if (v == null) bindAllocation(null, mExportVarIdx_touchPoints); + else bindAllocation(v.getAllocation(), mExportVarIdx_touchPoints); +} + +public ScriptField_Point get_touchPoints() { + return mExportVar_touchPoints; +} + +private Allocation mExportVar_intPointer; +public void bind_intPointer(Allocation v) { + mExportVar_intPointer = v; + if (v == null) bindAllocation(null, mExportVarIdx_intPointer); + else bindAllocation(v, mExportVarIdx_intPointer); +} + +public Allocation get_intPointer() { + return mExportVar_intPointer; +} + </pre> + +<p>A <code>get</code> method and a special method named <code>bind_<em>pointer_name</em></code> +(instead of a <code>set()</code> method) is generated. This method allows you to bind the memory +that is allocated in the Android VM to the Renderscript runtime (you cannot allocate +memory in your <code>.rs</code> file). For more information, see <a href="#memory">Working +with Allocated Memory</a>. +</p> + + <h2 id="mem-allocation">Memory Allocation APIs</h2> <p>Applications that use Renderscript still run in the Android VM. The actual Renderscript code, however, runs natively and @@ -693,7 +699,8 @@ communicated back to the Android framework layer for efficiency purposes. The la that is set from the Android framework is always returned during a call to a <code>get</code> method. However, when Android framework code modifies a variable, that change can be communicated to the Renderscript runtime automatically or synchronized at a later time. If you need to send data -from the Renderscript runtime to the Android framework layer, you can use the <code>rsSendToClient()</code> function +from the Renderscript runtime to the Android framework layer, you can use the +<a href="{@docRoot}reference/renderscript/rs__core_8rsh.html"><code>rsSendToClient()</code></a> function to overcome this limitation. </p> <p>When working with dynamically allocated memory, any changes at the Renderscript runtime layer are propagated diff --git a/docs/html/guide/topics/resources/localization.jd b/docs/html/guide/topics/resources/localization.jd index 9affb15..c2b668d 100755 --- a/docs/html/guide/topics/resources/localization.jd +++ b/docs/html/guide/topics/resources/localization.jd @@ -186,7 +186,7 @@ speak. </p> and can include other types of resources such as animations.
<br>
<code> res/drawable/</code>(required directory holding at least
- one graphic file, for the application's icon in the Market)<br>
+ one graphic file, for the application's icon on Google Play)<br>
<code> res/layout/</code> (required directory holding an XML
file that defines the default layout)<br>
<code> res/anim/</code> (required if you have any
@@ -507,7 +507,7 @@ the new locale. </p> <h2 id="publishing">Publishing Localized Applications</h2>
-<p>The Android Market is
+<p>The Google Play is
the main application distribution system for Android devices. To publish a
localized application, you need to sign your application, version it, and go
through all the other steps described in <a
@@ -521,7 +521,7 @@ different locale, follow these guidelines:</p> href="{@docRoot}guide/publishing/app-signing.html#strategies">Signing
Strategies</a>. </li>
<li>Give each .apk file a different application name. Currently it is
-impossible to put two applications into the Android Market that have exactly the
+impossible to publish two applications on Google Play that have exactly the
same name.</li>
<li>Include a complete set of default resources in each .apk file.</li>
</ul>
@@ -638,7 +638,7 @@ border="0"></td> <tr>
<td valign="top" align="center"><img src="../../../images/resources/arrow.png" alt="arrow" width="26"
border="0"></td>
- <td>Upload your .apk file or files to Market, selecting the appropriate
+ <td>Upload your .apk file or files to Google Play, selecting the appropriate
languages as
you upload. (For more details, see <a
href="{@docRoot}guide/publishing/publishing.html">Publishing Your
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd index 380791a..b33a097 100644 --- a/docs/html/guide/topics/resources/providing-resources.jd +++ b/docs/html/guide/topics/resources/providing-resources.jd @@ -287,9 +287,8 @@ names.</p> from the SIM card in the device. For example, <code>mcc310</code> is U.S. on any carrier, <code>mcc310-mnc004</code> is U.S. on Verizon, and <code>mcc208-mnc00</code> is France on Orange.</p> - <p>If the device uses a radio connection (GSM phone), the MCC comes - from the SIM, and the MNC comes from the network to which the - device is connected.</p> + <p>If the device uses a radio connection (GSM phone), the MCC and MNC values come + from the SIM card.</p> <p>You can also use the MCC alone (for example, to include country-specific legal resources in your application). If you need to specify based on the language only, then use the <em>language and region</em> qualifier instead (discussed next). If you decide to use the MCC and diff --git a/docs/html/guide/topics/resources/string-resource.jd b/docs/html/guide/topics/resources/string-resource.jd index ecd2d48..5f5484e 100644 --- a/docs/html/guide/topics/resources/string-resource.jd +++ b/docs/html/guide/topics/resources/string-resource.jd @@ -358,11 +358,14 @@ values, with non-exhaustive examples in parentheses: <pre> int count = getNumberOfsongsAvailable(); Resources res = {@link android.content.Context#getResources()}; -String songsFound = res.{@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString}(R.plurals.numberOfSongsAvailable, count, count); +String songsFound = res.<a +href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)" +>getQuantityString</a>(R.plurals.numberOfSongsAvailable, count, count); </pre> -<p>When using the {@link android.content.res.Resources#getQuantityString(int,int) -getQuantityString()} method, you need to pass the {@code count} twice if your string includes + +<p>When using the <a +href="{@docRoot}reference/android/content/res/Resources.html#getQuantityString(int, int, java.lang.Object...)">{@code +getQuantityString()}</a> method, you need to pass the {@code count} twice if your string includes <a href="#FormattingAndStyling">string formatting</a> with a number. For example, for the string {@code %d songs found}, the first {@code count} parameter selects the appropriate plural string and the second {@code count} parameter is inserted into the {@code %d} placeholder. If your plural diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd index 75a1716..43903dc 100644 --- a/docs/html/guide/topics/sensors/index.jd +++ b/docs/html/guide/topics/sensors/index.jd @@ -43,7 +43,7 @@ device's temperature sensor and humidity sensor to calculate and report the dewp application might use the geomagnetic field sensor and accelerometer to report a compass bearing.</p> -<p>The Android platform supports four broad categories of sensors:</p> +<p>The Android platform supports three broad categories of sensors:</p> <ul> <li>Motion sensors diff --git a/docs/html/guide/topics/sensors/sensors_overview.jd b/docs/html/guide/topics/sensors/sensors_overview.jd index 3c5e94c..543872c 100644 --- a/docs/html/guide/topics/sensors/sensors_overview.jd +++ b/docs/html/guide/topics/sensors/sensors_overview.jd @@ -606,7 +606,7 @@ sensor is present on a device so your app can run successfully. You have two opt that a given sensor is present on a device:</p> <ul> <li>Detect sensors at runtime and enable or disable application features as appropriate.</li> - <li>Use Android Market filters to target devices with specific sensor configurations.</li> + <li>Use Google Play filters to target devices with specific sensor configurations.</li> </ul> <p>Each option is discussed in the following sections.</p> @@ -633,9 +633,9 @@ whether there's a pressure sensor on a device:</p> } </pre> -<h4>Using Android Market filters to target specific sensor configurations</h4> +<h4>Using Google Play filters to target specific sensor configurations</h4> -<p>If you are publishing your application on Android Market you can use the +<p>If you are publishing your application on Google Play you can use the <a href="{@docRoot}guide//topics/manifest/uses-feature-element.html"><code><uses-feature> </code></a> element in your manifest file to filter your application from devices that do not have the appropriate sensor configuration for your application. The @@ -650,7 +650,7 @@ following is an example manifest entry that filters apps that do not have an acc </pre> <p>If you add this element and descriptor to your application's manifest, users will see your -application on Android Market only if their device has an accelerometer.</p> +application on Google Play only if their device has an accelerometer.</p> <p>You should set the descriptor to <code>android:required="true"</code> only if your application relies entirely on a specific sensor. If your application uses a sensor for some functionality, but diff --git a/docs/html/guide/topics/ui/accessibility/apps.jd b/docs/html/guide/topics/ui/accessibility/apps.jd new file mode 100644 index 0000000..dc91638 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -0,0 +1,574 @@ +page.title=Making Applications Accessible +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>In this document</h2> + <ol> + <li><a href="#label-ui">Labeling User Interface Elements</a></li> + <li><a href="#focus-nav">Enabling Focus Navigation</a> + <ol> + <li><a href="#focus-enable">Enabling view focus</a></li> + <li><a href="#focus-order">Controlling focus order</a></li> + </ol> + </li> + <li><a href="#custom-views">Building Accessible Custom Views</a> + <ol> + <li><a href="#directional-control">Handling directional controller clicks</a></li> + <li><a href="#accessibility-methods">Implementing accessibility API methods</a></li> + <li><a href="#send-events">Sending accessibility events</a></li> + <li><a href="#populate-events">Populating accessibility events</a></li> + </ol> + </li> + <li><a href="#test">Testing Accessibility</a> + <ol> + <li><a href="#test-audibles">Testing audible feedback</a></li> + <li><a href="#test-navigation">Testing focus navigation</a></li> + </ol> + </li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + <li>{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat}</li> + <li>{@link android.view.View.AccessibilityDelegate}</li> + <li>{@link android.support.v4.view.AccessibilityDelegateCompat}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + <li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a> + </li> + <li><a href="{@docRoot}design/index.html">Android Design</a></li> + </ol> + +</div> +</div> + +<p>Applications built for Android are accessible to users with visual, physical or age-related +disabilities when they activate accessibility features and services on a device. By default, +these services make your application more accessible. However, there are further steps you should +take to optimize the accessibility of your application and ensure a pleasant experience for all your +users.</p> + +<p>Making sure your application is accessible to all users is relatively easy, particularly when you +use framework-provided user interface components. If you only use these standard components for your +application, there are just a few steps required to ensure your application is accessible:</p> + +<ol> + <li>Label your {@link android.widget.ImageButton}, {@link android.widget.ImageView}, {@link +android.widget.EditText}, {@link android.widget.CheckBox} and other user interface controls using +the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> + {@code android:contentDescription}</a> attribute.</li> + <li>Make all of your user interface elements accessible with a directional controller, + such as a trackball or D-pad.</li> + <li>Test your application by turning on accessibility services like TalkBack and Explore by + Touch, and try using your application using only directional controls.</li> +</ol> + +<p>Developers who create custom controls that extend from the {@link android.view.View} class have +some additional responsibilities for making sure their components are accessible for users. This +document also discusses how to make custom view controls compatible with accessibility services.</p> + + +<h2 id="label-ui">Labeling User Interface Elements</h2> + +<p>Many user interface controls rely on visual cues to inform users of their meaning. For +example, a note-taking application might use an {@link android.widget.ImageButton} with a +picture of a plus sign to indicate that the user can add a new note. Or, an {@link +android.widget.EditText} component may have a label near it that indicates its purpose. When a user +with impaired vision accesses your application, these visual cues are often useless.</p> + +<p>To provide textual information about interface controls (as an alternative to the visual cues), +use the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute. The text you provide in this attribute is not +visible on the screen, but if a user has enabled accessibility services that provide audible +prompts, then the description in this attribute is read aloud to the user.</p> + +<p>Set the <a href="{@docRoot}reference/android/view/View.html#attr_android:contentDescription"> +{@code android:contentDescription}</a> attribute for every {@link android.widget.ImageButton}, +{@link android.widget.ImageView}, {@link android.widget.EditText}, {@link android.widget.CheckBox} +in your application's user interface, and on any other input controls that might require additional +information for users who are not able to see it.</p> + +<p>For example, the following {@link android.widget.ImageButton} sets the content description for +the plus button to the {@code add_note} string resource, which could be defined as “Add note" for an +English language interface:</p> + +<pre> +<ImageButton + android:id=”@+id/add_note_button” + android:src=”@drawable/add_note” + android:contentDescription=”@string/add_note”/> +</pre> + +<p>By including the description, speech-based accessibility services can announce "Add note" when a +user moves focus to this button or hovers over it.</p> + +<p class="note"><strong>Note:</strong> For {@link android.widget.EditText} fields, provide an +<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:hint">android:hint</a> +attribute to help users understand what content is expected.</p> + +<h2 id="focus-nav">Enabling Focus Navigation</h2> + +<p>Focus navigation allows users with disabilities to step through user interface controls using a +directional controller. Directional controllers can be physical, such as a clickable trackball, +directional pad (D-pad) or arrow keys, tab key navigation with an attached keyboard or a software +application, such as the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a>, that provides an on-screen directional control.</p> + +<p>A directional controller is a primary means of navigation for many users. +Verify that all user interface (UI) controls in your application are accessible +without using the touchscreen and that clicking with the center button (or OK button) of a +directional controller has the same effect as touching the controls on the touchscreen. For +information on testing directional controls, see <a href="#test-navigation">Testing focus +navigation</a>.</p> + +<h3 id="focus-enable">Enabling view focus</h3> + +<p>A user interface element is accessible using directional controls when its +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute is set to {@code true}. This setting allows users to focus +on the element using the directional controls and then interact with it. The user interface controls +provided by the Android framework are focusable by default and visually indicate focus by changing +the control’s appearance.</p> + +<p>Android provides several APIs that let you control whether a user interface control is focusable +and even request that a control be given focus:</p> + +<ul> + <li>{@link android.view.View#setFocusable setFocusable()}</li> + <li>{@link android.view.View#isFocusable isFocusable()}</li> + <li>{@link android.view.View#requestFocus requestFocus()}</li> +</ul> + +<p>When working with a view that is not focusable by default, you can make it focusable from the XML +layout file by setting the +<a href="{@docRoot}reference/android/view/View.html#attr_android:focusable"> +{@code android:focusable}</a> attribute to {@code true} or by using the {@link +android.view.View#setFocusable setFocusable()} method.</p> + +<h3 id="focus-order">Controlling focus order</h3> + +<p>When users navigate in any direction using directional controls, focus is passed from one +user interface element (View) to another, as determined by the focus ordering. The ordering of the +focus movement is based on an algorithm that finds the nearest neighbor in a given direction. In +rare cases, the default algorithm may not match the order that you intended for your UI. In these +situations, you can provide explicit overrides to the ordering using the following XML attributes in +the layout file:</p> + +<dl> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a></dt> + <dd>Defines the next view to receive focus when the user navigates down.</dd> + <a><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusLeft" +>{@code android:nextFocusLeft}</a></dt> + <dd>Defines the next view to receive focus when the user navigates left.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusRight" +>{@code android:nextFocusRight}</a></dt> + <dd>Defines the next view to receive focus when the user navigates right.</dd> + <dt><a href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a></dt> + <dd>Defines the next view to receive focus when the user navigates up.</dd> +</dl> + +<p>The following example XML layout shows two focusable user interface elements where the <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusDown" +>{@code android:nextFocusDown}</a> and <a +href="{@docRoot}reference/android/view/View.html#attr_android:nextFocusUp" +>{@code android:nextFocusUp}</a> attributes have been explicitly set. The {@link android.widget.TextView} is +located to the right of the {@link android.widget.EditText}. However, since these properties have +been set, the {@link android.widget.TextView} element can now be reached by pressing the down arrow +when focus is on the {@link android.widget.EditText} element: </p> + +<pre> +<LinearLayout android:orientation="horizontal" + ... > + <EditText android:id="@+id/edit" + android:nextFocusDown=”@+id/text” + ... /> + <TextView android:id="@+id/text" + android:focusable=”true” + android:text="Hello, I am a focusable TextView" + android:nextFocusUp=”@id/edit” + ... /> +</LinearLayout> +</pre> + +<p>When modifying focus order, be sure that the navigation works as expected in all directions from +each user interface control and when navigating in reverse (to get back to where you came from).</p> + +<p class="note"><strong>Note:</strong> You can modify the focus order of user interface components +at runtime, using methods such as {@link android.view.View#setNextFocusDownId setNextFocusDownId()} +and {@link android.view.View#setNextFocusRightId setNextFocusRightId()}.</p> + + +<h2 id="custom-views">Building Accessible Custom Views</h2> + +<p>If your application requires a <a href="{@docRoot}guide/topics/ui/custom-components.html">custom +view component</a>, you must do some additional work to ensure that your custom view is accessible. +These are the main tasks for ensuring the accessibility of your view:</p> + +<ul> + <li>Handle directional controller clicks</li> + <li>Implement Accessibility API methods</li> + <li>Send {@link android.view.accessibility.AccessibilityEvent} objects specific to your custom view</li> + <li>Populate {@link android.view.accessibility.AccessibilityEvent} and {@link + android.view.accessibility.AccessibilityNodeInfo} for your view</li> +</ul> + + +<h3 id="directional-control">Handling directional controller clicks</h3> + +<p>On most devices, clicking a view using a directional controller sends a {@link +android.view.KeyEvent} with {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER} to the view currently +in focus. All standard Android views already handle {@link +android.view.KeyEvent#KEYCODE_DPAD_CENTER} appropriately. When building a custom {@link +android.view.View} control, make sure this event has the same effect as touching the view on the +touchscreen. </p> + +<p>Your custom control should also treat the {@link android.view.KeyEvent#KEYCODE_ENTER} event the +same as {@link android.view.KeyEvent#KEYCODE_DPAD_CENTER}. This approach makes interaction from a +full keyboard much easier for users.</p> + + +<h3 id="accessibility-methods">Implementing accessibility API methods</h3> + +<p>Accessibility events are messages about users interaction with visual interface components in +your application. These messages are handled by <a href="services.html">Accessibility Services</a>, +which use the information in these events to produce supplemental feedback and prompts when users +have enabled accessibility services. As of Android 4.0 (API Level 14) and higher, the methods for +generating accessibility events have been expanded to provide more detailed information beyond the +{@link android.view.accessibility.AccessibilityEventSource} interface introduced in Android 1.6 (API +Level 4). The expanded accessibility methods are part of the {@link android.view.View} class as well +as the {@link android.view.View.AccessibilityDelegate} class. The methods are as follows:</p> + +<dl> + <dt>{@link android.view.View#sendAccessibilityEvent sendAccessibilityEvent()}</dt> + <dd>(API Level 4) This method is called when a user takes action on a view. The event is +classified with a user action type such as {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED TYPE_VIEW_CLICKED}. You typically do +not need to implement this method unless you are creating a custom view.</dd> + + <dt>{@link android.view.View#sendAccessibilityEventUnchecked +sendAccessibilityEventUnchecked()}</dt> + <dd>(API Level 4) This method is used when the calling code needs to directly control the check +for accessibility being enabled on the device ({@link +android.view.accessibility.AccessibilityManager#isEnabled AccessibilityManager.isEnabled()}). If +you do implement this method, you must assume that the calling method has already checked that +accessibility is enabled and the result is {@code true}. You typically do not need to implement this +method for a custom view.</dd> + + <dt>{@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} </dt> + <dd>(API Level 4) The system calls this method when your custom view generates an +accessibility event. As of API Level 14, the default implementation of this method calls {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} for this view and +then the {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()} method for each child of this view. In order to support +accessibility services on revisions of Android <em>prior</em> to 4.0 (API Level 14) you +<em>must</em> override this method and populate {@link +android.view.accessibility.AccessibilityEvent#getText} with descriptive text for your custom +view.</dd> + + <dt>{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()}</dt> + <dd>(API Level 14) This method sets the text output of an {@link +android.view.accessibility.AccessibilityEvent} for your view. This method is also called if the +view is a child of a view which generates an accessibility event. + + <p class="note"><strong>Note:</strong> Modifying additional attributes beyond the text within +this method potentially overwrites properties set by other methods. So, while you are able modify +attributes of the accessibility event with this method, you should limit these changes +to text content only and use the {@link android.view.View#onInitializeAccessibilityEvent +onInitializeAccessibilityEvent()} method to modify other properties of the event.</p> + + <p class="note"><strong>Note:</strong> If your implementation of this event calls for completely +overiding the output text without allowing other parts of your layout to modify its content, then +do not call the super implementation of this method in your code.</p> + </dd> + + <dt>{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method to obtain additional information about the +state of the view, beyond text content. If your custom view provides interactive control beyond a +simple {@link android.widget.TextView} or {@link android.widget.Button}, you should override this +method and set the additional information about your view into the event using this method, such as +password field type, checkbox type or states that provide user interaction or feedback. If you +do override this method, you must call its super implementation and then only modify properties +that have not been set by the super class.</dd> + + <dt>{@link android.view.View#onInitializeAccessibilityNodeInfo +onInitializeAccessibilityNodeInfo()}</dt> + <dd>(API Level 14) This method provides accessibility services with information about the state of +the view. The default {@link android.view.View} implementation sets a standard set of view +properties, but if your custom view provides interactive control beyond a simple {@link +android.widget.TextView} or {@link android.widget.Button}, you should override this method and set +the additional information about your view into the {@link +android.view.accessibility.AccessibilityNodeInfo} object handled by this method.</dd> + + <dt>{@link android.view.ViewGroup#onRequestSendAccessibilityEvent +onRequestSendAccessibilityEvent()}</dt> + <dd>(API Level 14) The system calls this method when a child of your view has generated an +{@link android.view.accessibility.AccessibilityEvent}. This step allows the the parent view to amend +the accessibility event with additional information. You should implement this method only if your +custom view can have child views and if the parent view can provide context information to the +accessibility event that would be useful to accessibility services.</dd> +</dl> + +<p>In order to support these accessibility methods for a custom view, you should take one of the +following approaches:</p> + +<ul> + <li>If your application targets Android 4.0 (API level 14) and higher, override and implement the +accessibility methods listed above directly in your custom view class.</li> + <li>If your custom view is intended to be compatible with Android 1.6 (API Level 4) and above, add +the Android <a href="{@docRoot}sdk/compatibility-library.html">Support Library</a>, revision 5 or +higher, to your project. Then, within your custom view class, call the +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()} method to implement the accessibility methods +above. For an example of this approach, see the Android Support Library (revision 5 or higher) +sample {@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}) + </li> +</ul> + +<p>In either case, you should implement the following accessibility methods for your custom view +class:</p> + +<ul> + <li>{@link android.view.View#dispatchPopulateAccessibilityEvent + dispatchPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onPopulateAccessibilityEvent + onPopulateAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityEvent + onInitializeAccessibilityEvent()}</li> + <li>{@link android.view.View#onInitializeAccessibilityNodeInfo + onInitializeAccessibilityNodeInfo()}</li> +</ul> + +<p>For more information about implementing these methods, see <a href="#populate-events">Populating +Accessibility Events</a>.</p> + + +<h3 id="send-events">Sending accessibility events</h3> + +<p>Depending on the specifics of your custom view, it may need to send {@link +android.view.accessibility.AccessibilityEvent} objects at a different times or for events not +handled by the default implementation. The {@link android.view.View} class provides a default +implementation for these event types:</p> + +<ul> + <li>Starting with API Level 4: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_LONG_CLICKED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_FOCUSED}</li> + </ul> + </li> + <li>Starting with API Level 14: + <ul> + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_SCROLLED}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_ENTER}</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_HOVER_EXIT}</li> + </ul> + </li> +</ul> + +<p class="note"><strong>Note:</strong> Hover events are associated with the Explore by +Touch feature, which uses these events as triggers for providing audible prompts for user interface +elements.</p> + +<p>In general, you should send an {@link android.view.accessibility.AccessibilityEvent} whenever the +content of your custom view changes. For example, if you are implementing a custom slider bar that +allows a user to select a numeric value by pressing the left or right arrows, your custom view +should emit an event of type {@link +android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} whenever the slider +value changes. The following sample code demonstrates the use of the {@link +android.view.accessibility.AccessibilityEventSource#sendAccessibilityEvent +sendAccessibilityEvent()} method to report this event.</p> + +<pre> +@Override +public boolean onKeyUp (int keyCode, KeyEvent event) { + if (keyCode == KeyEvent.KEYCODE_DPAD_LEFT) { + mCurrentValue--; + sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); + return true; + } + ... +} +</pre> + + +<h3 id="populate-events">Populating accessibility events</h3> + +<p>Each {@link android.view.accessibility.AccessibilityEvent} has a set of required properties that +describe the current state of the view. These properties include things such as the view’s class +name, content description and checked state. The specific properties required for each event type +are described in the {@link android.view.accessibility.AccessibilityEvent} reference documentation. +The {@link android.view.View} implementation provides default values for these properties. Many of +these values, including the class name and event timestamp, are provided automatically. If you are +creating a custom view component, you must provide some information about the content and +characteristics of the view. This information may be as simple as a button label, but may also +include additional state information that you want to add to the event.</p> + +<p>The minimum requirement for providing information to accessibility services with a custom +view is to implement {@link android.view.View#dispatchPopulateAccessibilityEvent +dispatchPopulateAccessibilityEvent()}. This method is called by the system to request +information for an {@link android.view.accessibility.AccessibilityEvent} and makes your custom +view compatible with accessibility services on Android 1.6 (API Level 4) and higher. The +following example code demonstrates a basic implementation of this method.</p> + +<pre> +@Override +public void dispatchPopulateAccessibilityEvent(AccessibilityEvent event) { + super.dispatchPopulateAccessibilityEvent(event); + // Call the super implementation to populate its text to the event, which + // calls onPopulateAccessibilityEvent() on API Level 14 and up. + + // In case this is running on a API revision earlier that 14, check + // the text content of the event and add an appropriate text + // description for this custom view: + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } +} +</pre> + +<p>On Android 4.0 (API Level 14) and higher, the {@link +android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods are the recommended way to populate or modify the information in an {@link +android.view.accessibility.AccessibilityEvent}. Use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} method +specifically for adding or modifying the text content of the event, which is turned into audible +prompts by accessibility services such as TalkBack. Use the +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} method for +populating additional information about the event, such as the selection state of the view.</p> + +<p>In addition, you should also implement the +{@link android.view.View#onInitializeAccessibilityNodeInfo onInitializeAccessibilityNodeInfo()} +method. {@link android.view.accessibility.AccessibilityNodeInfo} objects populated by this method +are used by accessibility services to investigate the view hierarchy that generated an accessibility +event after receiving that event, to obtain a more detailed context information and provide +appropriate feedback to users.</p> + +<p>The example code below shows how override these three methods by using +{@link android.support.v4.view.ViewCompat#setAccessibilityDelegate +ViewCompat.setAccessibilityDelegate()}. Note that this sample code requires that the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> for API Level 4 (revision 5 +or higher) is added to your project.</p> + +<pre> +ViewCompat.setAccessibilityDelegate(new AccessibilityDelegateCompat() { + @Override + public void onPopulateAccessibilityEvent(View host, AccessibilityEvent event) { + super.onPopulateAccessibilityEvent(host, event); + // We call the super implementation to populate its text for the + // event. Then we add our text not present in a super class. + // Very often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + event.getText().add(text); + } + } + @Override + public void onInitializeAccessibilityEvent(View host, AccessibilityEvent event) { + super.onInitializeAccessibilityEvent(host, event); + // We call the super implementation to let super classes + // set appropriate event properties. Then we add the new property + // (checked) which is not supported by a super class. + event.setChecked(isChecked()); + } + @Override + public void onInitializeAccessibilityNodeInfo(View host, + AccessibilityNodeInfoCompat info) { + super.onInitializeAccessibilityNodeInfo(host, info); + // We call the super implementation to let super classes set + // appropriate info properties. Then we add our properties + // (checkable and checked) which are not supported by a super class. + info.setCheckable(true); + info.setChecked(isChecked()); + // Quite often you only need to add the text for the custom view. + CharSequence text = getText(); + if (!TextUtils.isEmpty(text)) { + info.setText(text); + } + } +} +</pre> + +<p>On applications targeting Android 4.0 (API Level 14) and higher, these methods can be implemented +directly in your custom view class. For another example of this approach, see the Android +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> (revision 5 or higher) sample +{@code AccessibilityDelegateSupportActivity} in +({@code <sdk>/extras/android/support/v4/samples/Support4Demos/}).</p> + +<p class="note"><strong>Note:</strong> You may find information on implementing accessibility for +custom views written prior to Android 4.0 that describes the use of the +{@link android.view.View#dispatchPopulateAccessibilityEvent dispatchPopulateAccessibilityEvent()} +method for populating AccessibilityEvents. As of the Android 4.0 release, however, the recommended +approach is to use the +{@link android.view.View#onPopulateAccessibilityEvent onPopulateAccessibilityEvent()} and +{@link android.view.View#onInitializeAccessibilityEvent onInitializeAccessibilityEvent()} +methods.</p> + + +<h2 id="test">Testing Accessibility</h2> + +<p>Testing the accessibility of your application is an important part of ensuring your users have a +great experience. You can test the most important parts of accessibility by testing your application +with audible feedback enabled and testing navigation within your application using directional +controls.</p> + +<h3 id="test-audibles">Testing audible feedback</h3> +<p>You can simulate the experience for many users by enabling an accessibility service that speaks +as you move around the screen. The Explore by Touch accessibility service, which is available on +devices with Android 4.0 and later. The <a +href="https://play.google.com/store/apps/details?id=com.google.android.marvin.talkback">TalkBack</a> +accessibility service, by the <a href="http://code.google.com/p/eyes-free/">Eyes-Free +Project</a> comes preinstalled on many Android devices.</p> + +<p>To enable TalkBack on revisions of Android prior to Android 4.0:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select <strong>Accessibility</strong> to enable it.</li> + <li>Select <strong>TalkBack</strong> to enable it.</li> +</ol> + +<p class="note"><strong>Note:</strong> If the TalkBack accessibility service is not available, you +can install it for free from <a href="http://play.google.com">Google Play</a>.</p> + +<p>To enable Explore by Touch on Android 4.0 and later:</p> +<ol> + <li>Launch the Settings application.</li> + <li>Navigate to the <strong>Accessibility</strong> category and select it.</li> + <li>Select the <strong>TalkBack</strong> to enable it.</li> + <li>Return to the <strong>Accessibility</strong> category and select <strong>Explore by +Touch</strong> to enable it. + <p class="note"><strong>Note:</strong> You must turn on TalkBack <em>first</em>, otherwise this +option is not available.</p> + </li> +</ol> + +<h3 id="test-navigation">Testing focus navigation</h3> + +<p>As part of your accessibility testing, you can test navigation of your application using focus, +even if your test devices does not have a directional controller. The <a +href="{@docRoot}guide/developing/tools/emulator.html">Android Emulator</a> provides a +simulated directional controller that you can easily use to test navigation. You can also use a +software-based directional controller, such as the one provided by the +<a href="https://play.google.com/store/apps/details?id=com.googlecode.eyesfree.inputmethod.latin"> +Eyes-Free Keyboard</a> to simulate use of a D-pad.</p> diff --git a/docs/html/guide/topics/ui/accessibility/index.jd b/docs/html/guide/topics/ui/accessibility/index.jd new file mode 100644 index 0000000..414d5f3 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/index.jd @@ -0,0 +1,55 @@ +page.title=Accessibility +parent.title=User Interface +parent.link=../index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications Accessible</a> + </li> + <li><a href="{@docRoot}guide/topics/ui/accessibility/services.html">Building Accessibility + Services</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>Many Android users have disabilities that require them to interact with their Android devices in +different ways. These include users who have visual, physical or age-related disabilities that +prevent them from fully seeing or using a touchscreen.</p> + +<p>Android provides accessibility features and services for helping these users navigate their +devices more easily, including text-to-speech, haptic feedback, trackball and D-pad navigation that +augment their experience. Android application developers can take advantage of these services to +make their applications more accessible and also build their own accessibility services.</p> + +<p>The following topics show you how to use the Android framework to make applications more +accessible.</p> + +<dl> + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making Applications +Accessible</a></strong> + </dt> + <dd>Development practices and API features to ensure your application is accessible to users with +disabilities.</dd> + + <dt><strong><a href="{@docRoot}guide/topics/ui/accessibility/service.html">Building Accessibility +Services</a></strong> + </dt> + <dd>How to use API features to build services that make other applications more accessible for +users.</dd> +</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd new file mode 100644 index 0000000..0dad4ec --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/services.jd @@ -0,0 +1,290 @@ +page.title=Building Accessibility Services +parent.title=Accessibility +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Topics</h2> + <ol> + <li><a href="#manifest">Manifest Declarations and Permissions</a> + <ol> + <li><a href="service-declaration">Accessibility service declaration</a></li> + <li><a href="#service-config">Accessibility service configuration</a></li> + </ol> + </li> + <li><a href="#methods">AccessibilityService Methods</a></li> + <li><a href="#event-details">Getting Event Details</a></li> + <li><a href="#examples">Example Code</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.accessibilityservice.AccessibilityService}</li> + <li>{@link android.accessibilityservice.AccessibilityServiceInfo}</li> + <li>{@link android.view.accessibility.AccessibilityEvent}</li> + <li>{@link android.view.accessibility.AccessibilityRecord}</li> + <li>{@link android.view.accessibility.AccessibilityNodeInfo}</li> + </ol> + + <h2>See also</h2> + <ol> + <li><a href="{@docRoot}training/accessibility/index.html">Implementing Accessibility</a></li> + </ol> + +</div> +</div> + +<p>An accessibility service is an application that provides user interface enhancements to +assist users with disabilities, or who may temporarily be unable to fully interact with a device. +For example, users who are driving, taking care of a young child or attending a very loud party +might need additional or alternative interface feedback.</p> + +<p>Android provides standard accessibility services, including TalkBack, and developers can +create and distribute their own services. This document explains the basics of building an +accessibility service.</p> + +<p>The ability for you to build and deploy accessibility services was introduced with Android +1.6 (API Level 4) and received significant improvements with Android 4.0 (API Level 14). The Android +Support Library was also updated with the release of Android 4.0 to provide support for these +enhanced accessibility features back to Android 1.6. Developers aiming for widely compatible +accessibility services are encouraged to use the +<a href="{@docRoot}sdk/compatibility-library.html">Support Library</a> and develop for the more +advanced accessibility features introduced in Android 4.0.</p> + + +<h2 id="manifest">Manifest Declarations and Permissions</h2> + +<p>Applications that provide accessibility services must include specific declarations in their + application manifests in order to be treated as an accessibility service by an Android system. + This section explains the required and optional settings for accessibility services.</p> + + +<h3 id="service-declaration">Accessibility service declaration</h3> + +<p>In order to be treated as an accessibility service, your application must include the +{@code service} element (rather than the {@code activity} element) within the {@code application} +element in its manifest. In addition, within the {@code service} element, you must also include an +accessibility service intent filter, as shown in the following sample:</p> + +<pre> +<application> + <service android:name=".MyAccessibilityService" + android:label="@string/accessibility_service_label"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + </service> +</application> +</pre> + +<p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level + 4) or higher.</p> + + +<h3 id="service-config">Accessibility service configuration</h3> + +<p>Accessibility services must also provide a configuration which specifies the types of +accessibility events that the service handles and additional information about the service. The +configuration of an accessibility service is contained in the {@link +android.accessibilityservice.AccessibilityServiceInfo} class. Your service can build and set a +configuration using an instance of this class and {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()} at runtime. +However, not all configuration options are available using this method.</p> + +<p>Beginning with Android 4.0, you can include a {@code <meta-data>} element in your manifest +with a reference to a configuration file, which allows you to set the full range of options for +your accessibility service, as shown in the following example:</p> + +<pre> +<service android:name=".MyAccessibilityService"> + ... + <meta-data + android:name="android.accessibilityservice" + android:resource="@xml/accessibility_service_config" /> +</service> +</pre> + +<p>This meta-data element refers to an XML file that you create in your application’s resource +directory ({@code <project_dir>/res/xml/accessibility_service_config.xml}). The following code +shows example contents for the service configuration file:</p> + +<pre> +<accessibility-service xmlns:android="http://schemas.android.com/apk/res/android" + android:description="@string/accessibility_service_description" + android:packageNames="com.example.android.apis" + android:accessibilityEventTypes="typeAllMask" + android:accessibilityFlags="flagDefault" + android:accessibilityFeedbackType="feedbackSpoken" + android:notificationTimeout="100" + android:canRetrieveWindowContent="true" + android:settingsActivity="com.example.android.accessibility.ServiceSettingsActivity" +/> +</pre> + +<p>One of the most important functions of the accessibility service configuration parameters is to +allow you to specify what types of accessibility events your service can handle. Being able to +specify this information enables accessibility services to cooperate with each other, and allows you +as a developer the flexibility to handle only specific events types from specific applications. The +event filtering can include the following criteria:</p> + +<ul> + <li><strong>Package Names</strong> - Specify the package names of applications whose accessibility +events you want your service to handle. If this parameter is omitted, your accessibility service is +considered available to service accessibility events for any application. This parameter can be set +in the accessibility service configuration files with the {@code android:packageNames} attribute as +a comma-separated list, or set using the {@link +android.accessibilityservice.AccessibilityServiceInfo#packageNames +AccessibilityServiceInfo.packageNames} member.</li> + <li><strong>Event Types</strong> - Specify the types of accessibility events you want your service +to handle. This parameter can be set in the accessibility service configuration files with the +{@code android:accessibilityEventTypes} attribute as a comma-separated list, or set using the +{@link android.accessibilityservice.AccessibilityServiceInfo#eventTypes +AccessibilityServiceInfo.eventTypes} member. </li> +</ul> + +<p>For more information about the XML attributes which can be used in the accessibility service + configuration file, follow these links to the reference documentation:</p> + +<ul> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_description">{@code android:description}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_packageNames">{@code android:packageNames}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityEventTypes">{@code android:accessibilityEventTypes}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFlags">{@code android:accessibilityFlags}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_accessibilityFeedbackType">{@code android:accessibilityFeedbackType}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_notificationTimeout">{@code android:notificationTimeout}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_canRetrieveWindowContent">{@code android:canRetrieveWindowContent}</a></li> + <li><a href="{@docRoot}reference/android/R.styleable.html#AccessibilityService_settingsActivity">{@code android:settingsActivity}</a></li> +</ul> + +<p>For more information about which configuration settings can be dynamically set at runtime, see +the {@link android.accessibilityservice.AccessibilityServiceInfo} reference documentation.</p> + + +<h2 id="methods">AccessibilityService Methods</h2> + +<p>An application that provides accessibility service must extend the {@link +android.accessibilityservice.AccessibilityService} class and override the following methods from +that class. These methods are presented in the order in which they are called by the Android system, +from when the service is started +({@link android.accessibilityservice.AccessibilityService#onServiceConnected onServiceConnected()}), +while it is running ({@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()}, +{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()}) to when it is +shut down ({@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()}).</p> + +<ul> + <li>{@link android.accessibilityservice.AccessibilityService#onServiceConnected +onServiceConnected()} - (optional) This system calls this method when it successfully connects to +your accessibility service. Use this method to do any one-time setup steps for your service, +including connecting to user feedback system services, such as the audio manager or device vibrator. +If you want to set the configuration of your service at runtime or make one-time adjustments, this +is a convenient location from which to call {@link +android.accessibilityservice.AccessibilityService#setServiceInfo setServiceInfo()}.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} - (required) This method is called back by the system when it detects an +{@link android.view.accessibility.AccessibilityEvent} that matches the event filtering parameters +specified by your accessibility service. For example, when the user clicks a button or focuses on a +user interface control in an application for which your accessibility service is providing feedback. +When this happens, the system calls this method of your service with the associated {@link +android.view.accessibility.AccessibilityEvent}, which you can then interpret and provide feedback to +the user. This method may be called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onInterrupt onInterrupt()} - +(required) This method is called when the system wants to interrupt the feedback your service is +providing, usually in response to a user taking action, such as moving focus to a different user +interface control than the one for which you are currently providing feedback. This method may be +called many times over the lifecycle of your service.</li> + + <li>{@link android.accessibilityservice.AccessibilityService#onUnbind onUnbind()} - (optional) +This method is called when the system is about to shutdown the accessibility service. Use this +method to do any one-time shutdown procedures, including de-allocating user feedback system +services, such as the audio manager or device vibrator.</li> +</ul> + +<p>These callback methods provide the basic structure for your accessibility service. It is up to +you to decide on how to process data provided by the Android system in the form of {@link +android.view.accessibility.AccessibilityEvent} objects and provide feedback to the user.</p> + + +<h2 id="event-details">Getting Event Details</h2> + +<p>The Android system provides information to accessibility services about the user interface +interaction through {@link android.view.accessibility.AccessibilityEvent} objects. Prior to Android +4.0, the information available in an accessibility event, while providing a significant amount of +detail about a user interface control selected by the user, typically provided limited contextual +information. In many cases, this missing context information might be critical to understanding the +meaning of the selected control.</p> + +<p>A typical example of an interface where context is of critical importance is a calendar or day +planner. If a user selects a 4:00 PM time slot in a Monday to Friday day list and the accessibility +service announces “4 PM”, but fails to indicate this is a Friday a Monday, the month or day, this is +hardly ideal feedback for the user. In this case, the context of a user interface control is of +critical importance to a user who wants to schedule a meeting.</p> + +<p>Android 4.0 significantly extends the amount of information that an accessibility service can +obtain about an user interface interaction by composing accessibility events based on the view +hierarchy. A view hierarchy is the set of user interface components that contain the component (its +parents) and the user interface elements that may be contained by that component (its children). In +this way, the Android system can provide much richer detail about accessibility events, allowing +accessibility services to provide more useful feedback to users.</p> + +<p>An accessibility service gets information about an user interface event through an {@link +android.view.accessibility.AccessibilityEvent} passed by the system to the service’s +{@link android.accessibilityservice.AccessibilityService#onAccessibilityEvent +onAccessibilityEvent()} callback method. This object provides details about the event, including the +type of object being acted upon, its descriptive text and other details. Starting in Android 4.0 +(and supported in previous releases through the {@link +android.support.v4.view.accessibility.AccessibilityEventCompat} object in the Support Library), you +can obtain additional information about the event using these calls:</p> + +<ul> + <li>{@link android.view.accessibility.AccessibilityEvent#getRecordCount +AccessibilityEvent.getRecordCount()} and {@link +android.view.accessibility.AccessibilityEvent#getRecord getRecord(int)} - These methods allow you to +retrieve the set of {@link android.view.accessibility.AccessibilityRecord} objects which contributed +to the {@link android.view.accessibility.AccessibilityEvent} passed to you by the system, which can +provide more context for your accessibility service.</li> + + <li>{@link android.view.accessibility.AccessibilityEvent#getSource +AccessibilityEvent.getSource()} - This method returns an {@link +android.view.accessibility.AccessibilityNodeInfo} object. This object allows you to request the +parents and children of the component that originated the accessibility event and investigate their +contents and state in order to provide + + <p class="caution"><strong>Important:</strong> The ability to investigate the full view +hierarchy from an {@link android.view.accessibility.AccessibilityEvent} potentially exposes private +user information to your accessibility service. For this reason, your service must request this +level of access through the accessibility <a href="#service-config">service configuration XML</a> +file, by including the {@code canRetrieveWindowContent} attribute and setting it to {@code true}. If +you do not include this setting in your service configuration xml file, calls to {@link +android.view.accessibility.AccessibilityEvent#getSource getSource()} fail.</p> + </li> +</ul> + + +<h2 id="examples">Example Code</h2> + +<p>The API Demo project contains two samples which can be used as a starting point for generating +accessibility services +({@code <sdk>/samples/<platform>/ApiDemos/src/com/example/android/apis/accessibility}): +</p> + +<ul> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/ClockBackService.html">ClockBackService</a> + - This service is based on the original implementation of {@link +android.accessibilityservice.AccessibilityService} and can be used as a base for developing basic +accessibility services that are compatible with Android 1.6 (API Level 4) and higher.</li> + <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/accessibility/TaskBackService.html">TaskBackService</a> + - This service is based on the enhanced accessibility APIs introduced in Android 4.0 (API Level +14). However, you can use the Android <a href="{@docRoot}sdk/compatibility-library.html">Support +Libary</a> to substitute classes introduced in later API levels (e.g., +{@link android.view.accessibility.AccessibilityRecord}, +{@link android.view.accessibility.AccessibilityNodeInfo} +) with equivalent support package classes (e.g., +{@link android.support.v4.view.accessibility.AccessibilityRecordCompat}, +{@link android.support.v4.view.accessibility.AccessibilityNodeInfoCompat} +) to make this example work with API versions back to Android 1.6 (API Level 4).</li> +</ul> diff --git a/docs/html/guide/topics/ui/actionbar.jd b/docs/html/guide/topics/ui/actionbar.jd index e59fa0f..bf7369a 100644 --- a/docs/html/guide/topics/ui/actionbar.jd +++ b/docs/html/guide/topics/ui/actionbar.jd @@ -349,7 +349,7 @@ of the following:</p> <li><strong>Frequently used</strong>: It's an action that your users need seven out of ten visits or they use it several times in a row. <p>Example frequent actions: "New message" in the Messaging app and -"Search" in Android Market.</p> +"Search" on Google Play.</p> </li> <li><strong>Important</strong>: It's an action that you need users to easily discover or, if it's diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd index 8b2792d..e251fe9 100644 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ b/docs/html/guide/topics/ui/layout-objects.jd @@ -163,7 +163,7 @@ refer to the ID using the syntax of a relative resource <td> <pre> <?xml version="1.0" encoding="utf-8"?> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android +<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android" android:layout_width="fill_parent" android:layout_height="wrap_content" android:background="@drawable/blue" diff --git a/docs/html/guide/topics/usb/adk.jd b/docs/html/guide/topics/usb/adk.jd index 4d5fbfa..c8949a3 100644 --- a/docs/html/guide/topics/usb/adk.jd +++ b/docs/html/guide/topics/usb/adk.jd @@ -97,6 +97,9 @@ page.title=Android Open Accessory Development Kit <li><a href="http://www.sparkfun.com/products/10748"> SparkFun</a></li> + <li><a href="http://troido.de/de/shoplsmallgbuy-android-stufflsmallg"> + Troido</a></li> + </ol> </div> </div> diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/wireless/bluetooth.jd index 76da08e..0567799 100644 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ b/docs/html/guide/topics/wireless/bluetooth.jd @@ -249,12 +249,20 @@ if (!mBluetoothAdapter.isEnabled()) { <p>A dialog will appear requesting user permission to enable Bluetooth, as shown in Figure 1. If the user responds "Yes," the system will begin to enable Bluetooth and focus will return to your application once the process completes (or fails).</p> -<p>If enabling Bluetooth succeeds, your Activity will receive the {@link + +<p>The {@code REQUEST_ENABLE_BT} constant passed to {@link +android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()} is a locally +defined integer (which must be greater than 0), that the system passes back to you in your +{@link +android.app.Activity#onActivityResult(int,int,Intent) onActivityResult()} implementation as the +<code>requestCode</code> parameter.</p> + +<p>If enabling Bluetooth succeeds, your activity receives the {@link android.app.Activity#RESULT_OK} result code in the {@link android.app.Activity#onActivityResult(int,int,Intent) onActivityResult()} callback. If Bluetooth was not enabled -due to an error (or the user responded "No") then the result code will be {@link -android.app.Activity#RESULT_CANCELED}.</p> +due to an error (or the user responded "No") then the result code is {@link +android.app.Activity#RESULT_CANCELED}.</p> </li> </ol> @@ -431,11 +439,11 @@ startActivity(discoverableIntent); <p>A dialog will be displayed, requesting user permission to make the device discoverable, as shown in Figure 2. If the user responds "Yes," then the device -will become discoverable for the specified amount of time. Your Activity will +will become discoverable for the specified amount of time. Your activity will then receive a call to the {@link android.app.Activity#onActivityResult(int,int,Intent) onActivityResult())} callback, with the result code equal to the duration that the device is discoverable. If the user responded "No" or if an error occurred, the result code will -be Activity.RESULT_CANCELLED.</p> +be {@link android.app.Activity#RESULT_CANCELED}.</p> <p class="note"><strong>Note:</strong> If Bluetooth has not been enabled on the device, then enabling device discoverability will automatically enable Bluetooth.</p> @@ -568,7 +576,7 @@ socket.</p> </ol> <p>The {@link android.bluetooth.BluetoothServerSocket#accept()} call should not -be executed in the main Activity UI thread because it is a blocking call and +be executed in the main activity UI thread because it is a blocking call and will prevent any other interaction with the application. It usually makes sense to do all work with a {@link android.bluetooth.BluetoothServerSocket} or {@link android.bluetooth.BluetoothSocket} in a new @@ -696,7 +704,7 @@ android.bluetooth.BluetoothSocket#connect()} method times out (after about 12 seconds), then it will throw an exception.</p> <p>Because {@link android.bluetooth.BluetoothSocket#connect()} is a blocking call, this connection -procedure should always be performed in a thread separate from the main Activity +procedure should always be performed in a thread separate from the main activity thread.</p> <p class="note">Note: You should always ensure that the device is not performing device discovery when you call {@link @@ -838,7 +846,7 @@ private class ConnectedThread extends Thread { try { // Read from the InputStream bytes = mmInStream.read(buffer); - // Send the obtained bytes to the UI Activity + // Send the obtained bytes to the UI activity mHandler.obtainMessage(MESSAGE_READ, bytes, -1, buffer) .sendToTarget(); } catch (IOException e) { @@ -847,14 +855,14 @@ private class ConnectedThread extends Thread { } } - /* Call this from the main Activity to send data to the remote device */ + /* Call this from the main activity to send data to the remote device */ public void write(byte[] bytes) { try { mmOutStream.write(bytes); } catch (IOException e) { } } - /* Call this from the main Activity to shutdown the connection */ + /* Call this from the main activity to shutdown the connection */ public void cancel() { try { mmSocket.close(); @@ -866,12 +874,12 @@ private class ConnectedThread extends Thread { <p>The constructor acquires the necessary streams and once executed, the thread will wait for data to come through the InputStream. When {@link java.io.InputStream#read(byte[])} returns with -bytes from the stream, the data is sent to the main Activity using a member +bytes from the stream, the data is sent to the main activity using a member Handler from the parent class. Then it goes back and waits for more bytes from the stream.</p> <p>Sending outgoing data is as simple as calling the thread's -<code>write()</code> method from the main Activity and passing in the bytes to +<code>write()</code> method from the main activity and passing in the bytes to be sent. This method then simply calls {@link java.io.OutputStream#write(byte[])} to send the data to the remote device.</p> diff --git a/docs/html/guide/topics/wireless/wifip2p.jd b/docs/html/guide/topics/wireless/wifip2p.jd index 4dd3d26..ec8e71e 100644 --- a/docs/html/guide/topics/wireless/wifip2p.jd +++ b/docs/html/guide/topics/wireless/wifip2p.jd @@ -333,7 +333,7 @@ protected void onCreate(Bundle savedInstanceState){ ... mManager = (WifiP2pManager) getSystemService(Context.WIFI_P2P_SERVICE); mChannel = mManager.initialize(this, getMainLooper(), null); - Receiver = new WiFiDirectBroadcastReceiver(manager, channel, this); + mReceiver = new WiFiDirectBroadcastReceiver(manager, channel, this); ... } </pre> @@ -364,13 +364,13 @@ protected void onCreate(Bundle savedInstanceState){ @Override protected void onResume() { super.onResume(); - registerReceiver(receiver, intentFilter); + registerReceiver(mReceiver, mIntentFilter); } /* unregister the broadcast receiver */ @Override protected void onPause() { super.onPause(); - unregisterReceiver(receiver); + unregisterReceiver(mReceiver); } </pre> diff --git a/docs/html/guide/tutorials/views/hello-mapview.jd b/docs/html/guide/tutorials/views/hello-mapview.jd index 458db4f..5217b6b 100644 --- a/docs/html/guide/tutorials/views/hello-mapview.jd +++ b/docs/html/guide/tutorials/views/hello-mapview.jd @@ -14,8 +14,8 @@ location:</p> href="http://code.google.com/android/add-ons/google-apis">http://code.google.com/android/add-ons/google-apis</a></p> <p>The Google APIs add-on requires Android 1.5 SDK or later release. After -installing the add-on in your SDK, set your project properties to use the build -target called "Google APIs Add-on". See the instructions for setting a build +installing the add-on in your SDK, set your project properties to use a <strong>Google +APIs</strong> build target. See the instructions for setting a build target in <a href="{@docRoot}guide/developing/eclipse-adt.html">Developing in Eclipse with ADT</a> or <a href="{@docRoot}guide/developing/other-ide.html">Developing in Other IDEs</a>, diff --git a/docs/html/images/avd-manager.png b/docs/html/images/avd-manager.png Binary files differindex c33d8a8..fd373f9 100644 --- a/docs/html/images/avd-manager.png +++ b/docs/html/images/avd-manager.png diff --git a/docs/html/images/billing_package.png b/docs/html/images/billing_package.png Binary files differindex 951e117..6e673c8 100644 --- a/docs/html/images/billing_package.png +++ b/docs/html/images/billing_package.png diff --git a/docs/html/images/developing/avd-dialog.png b/docs/html/images/developing/avd-dialog.png Binary files differindex d0e2eec..9dfbd68 100644 --- a/docs/html/images/developing/avd-dialog.png +++ b/docs/html/images/developing/avd-dialog.png diff --git a/docs/html/images/developing/ddms-network.png b/docs/html/images/developing/ddms-network.png Binary files differnew file mode 100644 index 0000000..5aa1290 --- /dev/null +++ b/docs/html/images/developing/ddms-network.png diff --git a/docs/html/images/developing/sdk-usb-driver.png b/docs/html/images/developing/sdk-usb-driver.png Binary files differindex 207d3d7..3489991 100644 --- a/docs/html/images/developing/sdk-usb-driver.png +++ b/docs/html/images/developing/sdk-usb-driver.png diff --git a/docs/html/images/efficient-downloads/DDMS.png b/docs/html/images/efficient-downloads/DDMS.png Binary files differnew file mode 100644 index 0000000..e7b0b94 --- /dev/null +++ b/docs/html/images/efficient-downloads/DDMS.png diff --git a/docs/html/images/efficient-downloads/graphs.png b/docs/html/images/efficient-downloads/graphs.png Binary files differnew file mode 100644 index 0000000..65faeaa --- /dev/null +++ b/docs/html/images/efficient-downloads/graphs.png diff --git a/docs/html/images/efficient-downloads/mobile_radio_state_machine.png b/docs/html/images/efficient-downloads/mobile_radio_state_machine.png Binary files differnew file mode 100644 index 0000000..e06608b --- /dev/null +++ b/docs/html/images/efficient-downloads/mobile_radio_state_machine.png diff --git a/docs/html/images/emulator-wvga800l.png b/docs/html/images/emulator-wvga800l.png Binary files differindex a214033..c92c1b9 100644 --- a/docs/html/images/emulator-wvga800l.png +++ b/docs/html/images/emulator-wvga800l.png diff --git a/docs/html/images/home/play_logo.png b/docs/html/images/home/play_logo.png Binary files differnew file mode 100644 index 0000000..b8e3ebf --- /dev/null +++ b/docs/html/images/home/play_logo.png diff --git a/docs/html/images/licensing_add_library.png b/docs/html/images/licensing_add_library.png Binary files differindex 3bbe6d5..257a628 100644 --- a/docs/html/images/licensing_add_library.png +++ b/docs/html/images/licensing_add_library.png diff --git a/docs/html/images/licensing_gapis_8.png b/docs/html/images/licensing_gapis_8.png Binary files differdeleted file mode 100644 index 480d989..0000000 --- a/docs/html/images/licensing_gapis_8.png +++ /dev/null diff --git a/docs/html/images/licensing_package.png b/docs/html/images/licensing_package.png Binary files differindex eb2c5cf..dc34473 100644 --- a/docs/html/images/licensing_package.png +++ b/docs/html/images/licensing_package.png diff --git a/docs/html/images/screens_support/avds-config.png b/docs/html/images/screens_support/avds-config.png Binary files differindex 3af1c39..c7d534c 100644 --- a/docs/html/images/screens_support/avds-config.png +++ b/docs/html/images/screens_support/avds-config.png diff --git a/docs/html/images/sdk_manager_packages.png b/docs/html/images/sdk_manager_packages.png Binary files differindex 19a7cb9..a0e8108 100644 --- a/docs/html/images/sdk_manager_packages.png +++ b/docs/html/images/sdk_manager_packages.png diff --git a/docs/html/images/training/cool-places.png b/docs/html/images/training/cool-places.png Binary files differnew file mode 100755 index 0000000..769b5b7 --- /dev/null +++ b/docs/html/images/training/cool-places.png diff --git a/docs/html/images/training/panoramio-grid.png b/docs/html/images/training/panoramio-grid.png Binary files differnew file mode 100755 index 0000000..45c0eb5 --- /dev/null +++ b/docs/html/images/training/panoramio-grid.png diff --git a/docs/html/index.jd b/docs/html/index.jd index 431a7d2..d3203bb 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -12,15 +12,13 @@ page.metaDescription=The official site for Android developers. Provides the Andr </div><!-- end homeTitle --> <div id="announcement-block"> <!-- total max width is 520px --> - <a href="{@docRoot}design/index.html"> - <img src="{@docRoot}images/home/android-design.png" -alt="Android Design" width="160px" style="padding:10px 33px 5px"/> - </a> + <img src="{@docRoot}images/home/play_logo.png" +alt="Google Play" width="120px" style="padding:10px 52px"/> <div id="announcement" style="width:275px"> - <p>Introducing <b>Android Design</b>: The place to learn about principles, building blocks, and patterns - for creating world-class Android user interfaces. Whether you're a UI professional or a developer - playing that role, these docs show you how to make good design decisions, big and small.</p> - <p><a href="{@docRoot}design/index.html">Android Design »</a></p> + <p>Introducing <strong>Google Play</strong>: An integrated digital content destination where +users buy and enjoy all of their favorite content in one place. It's the new destination for +Android apps!</p> + <p><a href="http://android-developers.blogspot.com/2012/03/introducing-google-play.html">Read more »</a></p> </div> <!-- end annoucement --> </div> <!-- end annoucement-block --> </div><!-- end topAnnouncement --> @@ -55,28 +53,32 @@ alt="Android Design" width="160px" style="padding:10px 33px 5px"/> <p><a href="{@docRoot}sdk/index.html">Learn more »</a></p> </td> </tr> + + <tr> <td colspan="2"><div class="seperator"> </div></td> </tr> <tr> - <td class="imageCell"><a href="http://market.android.com/publish"><img src="{@docRoot}assets/images/icon_market.jpg" style="padding:0" /></a></td> + <td class="imageCell"><a href="{@docRoot}design/index.html"><img src="{@docRoot}assets/images/icon_design.png" style="padding:5px" /></a></td> <td> - <h2 class="green">Publish</h2> - <p>Android Market is an open service that lets you distribute your apps to handsets.</p> - <p><a href="http://market.android.com/publish">Learn more »</a></p> + <h2 class="green">Design</h2> + <p>Learn about principles, building blocks, and patterns for creating world-class Android user interfaces.</p> + <p><a href="{@docRoot}design/index.html">Learn more »</a></p> </td> </tr> + <tr> <td colspan="2"><div class="seperator"> </div></td> </tr> <tr> - <td class="imageCell"><a href="http://source.android.com"><img src="{@docRoot}assets/images/icon_contribute.jpg" style="padding:0" /></a></td> + <td class="imageCell"><a href="http://play.google.com/apps/publish"><img src="{@docRoot}assets/images/icon_play.png" style="padding:0" /></a></td> <td> - <h2 class="green">Contribute</h2> - <p>Android Open Source Project gives you access to the entire platform source.</p> - <p><a href="http://source.android.com">Learn more »</a></p> + <h2 class="green">Publish</h2> + <p>Google Play is an open service that lets you distribute your apps to devices.</p> + <p><a href="http://play.google.com/apps/publish">Learn more »</a></p> </td> </tr> + <tr> <td colspan="2"><div class="seperator"> </div></td> </tr> @@ -182,8 +184,8 @@ href="{@docRoot}resources/dashboard/platform-versions.html">Learn more »</ 'desc': "<p>Run and debug your Android applications directly on one of these " + "devices. Modify and rebuild the Android operating system, and flash it onto " + "the phone. The Android Dev Phones are carrier-independent, and available for " - + "purchase by developers through their Android Market publisher accounts.</p><p> " - + "<a href='http://market.android.com/publish'>Visit Android Market " + + "purchase by developers through their Google Play publisher accounts.</p><p> " + + "<a href='http://play.google.com/apps/publish'>Visit Google Play " + "to learn more »</a></p>" }, */ diff --git a/docs/html/intl/ja/community/index.jd b/docs/html/intl/ja/community/index.jd index 490b23f..9739f0d 100644 --- a/docs/html/intl/ja/community/index.jd +++ b/docs/html/intl/ja/community/index.jd @@ -85,7 +85,7 @@ page.title=コミュニティ <li><b>Android マーケット ヘルプフォーラム</b> - Android マーケットに関する質問や問題の報告をするための、ウェブベースのディスカッション フォーラムです。 <ul> -<li>URL: <a href="http://www.google.com/support/forum/p/Android+Market?hl=ja">http://www.google.com/support/forum/p/Android+Market?hl=ja</a></li> +<li>URL: <a href="http://support.google.com/googleplay?hl=ja">http://support.google.com/googleplay?hl=ja</a></li> </ul> </li> diff --git a/docs/html/intl/ja/index.jd b/docs/html/intl/ja/index.jd index 8096247..fbbd88f 100644 --- a/docs/html/intl/ja/index.jd +++ b/docs/html/intl/ja/index.jd @@ -52,11 +52,11 @@ home=true <td colspan="2"><div class="seperator"> </div></td> </tr> <tr> - <td class="imageCell"><a href="http://www.android.com/market.html"><img src="{@docRoot}assets/images/icon_market.jpg" style="padding:0" /></a></td> + <td class="imageCell"><a href="http://play.google.com/apps/publish"><img src="{@docRoot}assets/images/icon_play.png" style="padding:0" /></a></td> <td> <h2 class="green">公開</h2> <p>Android マーケットは、アプリケーションを携帯端末に配信するためのオープン サービスです。</p> - <p><a href="http://market.android.com/publish/Home">詳細 »</a></p> + <p><a href="http://play.google.com/apps/publish">詳細 »</a></p> </td> </tr> <tr> @@ -148,7 +148,7 @@ home=true 'name':"Dev Phone 1", 'img':"devphone-large.png", 'title':"Android Dev Phone 1", - 'desc': "<p>この携帯電話を使用することで、開発した Android アプリケーションの実行とデバッグを行うことができます。Android オペレーティングシステムを変更してからリビルドし、携帯電話に書き込むことができます。Android Dev Phone 1 は携帯通信会社に依存しておらず、<a href='http://market.android.com/publish'>Android マーケット</a>に登録済みのデベロッパーなら誰でも購入可能です。</p><p><a href='/guide/developing/device.html#dev-phone-1'>Android Dev Phone 1 の詳細»</a></p>" + 'desc': "<p>この携帯電話を使用することで、開発した Android アプリケーションの実行とデバッグを行うことができます。Android オペレーティングシステムを変更してからリビルドし、携帯電話に書き込むことができます。Android Dev Phone 1 は携帯通信会社に依存しておらず、<a href='http://play.google.com/apps/publish'>Android マーケット</a>に登録済みのデベロッパーなら誰でも購入可能です。</p><p><a href='/guide/developing/device.html#dev-phone-1'>Android Dev Phone 1 の詳細»</a></p>" } } diff --git a/docs/html/intl/ja/resources/community-groups.jd b/docs/html/intl/ja/resources/community-groups.jd index ecedde1..3fd6601 100644 --- a/docs/html/intl/ja/resources/community-groups.jd +++ b/docs/html/intl/ja/resources/community-groups.jd @@ -85,7 +85,7 @@ page.title=コミュニティ <li><b>Android マーケット ヘルプフォーラム</b> - Android マーケットに関する質問や問題の報告をするための、ウェブベースのディスカッション フォーラムです。 <ul> -<li>URL: <a href="http://www.google.com/support/forum/p/Android+Market?hl=ja">http://www.google.com/support/forum/p/Android+Market?hl=ja</a></li> +<li>URL: <a href="http://support.google.com/googleplay?hl=ja">http://support.google.com/googleplay?hl=ja</a></li> </ul> </li> diff --git a/docs/html/offline.jd b/docs/html/offline.jd index 5f8e37ce..edd8eb0 100644 --- a/docs/html/offline.jd +++ b/docs/html/offline.jd @@ -40,7 +40,7 @@ tools</li> <p>Follow the guide to <a href="{@docRoot}sdk/installing.html">Installing the Android SDK</a>, which will help you setup your development environment.</p> -<h3>If you've installed new SDK components using the SDK and AVD Manager</h3> +<h3>If you've installed new SDK components using the Android SDK Manager</h3> <p>There's no additional setup.</p> diff --git a/docs/html/resources/articles/can-i-use-this-intent.jd b/docs/html/resources/articles/can-i-use-this-intent.jd index c527331..7787d31 100644 --- a/docs/html/resources/articles/can-i-use-this-intent.jd +++ b/docs/html/resources/articles/can-i-use-this-intent.jd @@ -68,4 +68,4 @@ but it only lets you react to the problem, you cannot predict it and update the UI accordingly to prevent the user from doing something that won't work. The technique described here can also be used at startup time to ask the user whether he'd like to install the missing package, you can then simply redirect -him to the Android Market by using the appropriate URI.</p>
\ No newline at end of file +him to Google Play by using the appropriate URI.</p>
\ No newline at end of file diff --git a/docs/html/resources/articles/contacts.jd b/docs/html/resources/articles/contacts.jd index 8365d29..374587b 100644 --- a/docs/html/resources/articles/contacts.jd +++ b/docs/html/resources/articles/contacts.jd @@ -298,10 +298,10 @@ platforms and one for Android 2.0 and beyond. If so, here's what you'll need to <li>At launch time, check the version of the SDK. The version of the SDK is available as {@link android.os.Build.VERSION#SDK android.os.Build.VERSION.SDK}.</li> <li>If the SDK version is greater or equal to 5 (Android 2.0), show a dialog -suggesting to the user that it's time to go to Market and find a new version of -the app. You can even provide a link to the new app on Market (see <a +suggesting to the user that it's time to go to Google Play and find a new version of +the app. You can even provide a link to the new app on Google Play (see <a href="{@docRoot}guide/publishing/publishing.html#marketintent">Using Intents -to Launch Market</a>). </li> +to Launch Google Play</a>). </li> </ul> <li>Change the new application:</li> <ul> @@ -311,14 +311,14 @@ and other new features of Android 2.0. </li> <li>Modify that application's AndroidManifest.xml file: </li> <ul> <li>Give the application a new name and a new package name. Currently -Android Market does not allow you to have two applications with the same +Google Play does not allow you to have two applications with the same name/package.</li> <li>Update (or add) the <code>android:minSdkVersion</code> attribute to the <code><uses-sdk></code> element. To use the new Contacts API, you should set the value of the attribute to "5" (or higher, as appropriate).</li> </ul> </ul> - <li>Publish both apps on Market, the old app one as an upgrade and the + <li>Publish both apps on Google Play, the old app one as an upgrade and the other as new. Make sure to explain the difference between the apps in their descriptions.</li> </ul> diff --git a/docs/html/resources/articles/creating-input-method.jd b/docs/html/resources/articles/creating-input-method.jd index e4b77f4..84c2704 100644 --- a/docs/html/resources/articles/creating-input-method.jd +++ b/docs/html/resources/articles/creating-input-method.jd @@ -3,248 +3,526 @@ parent.title=Articles parent.link=../browser.html?tag=article @jd:body - <div id="qv-wrapper"> <div id="qv"> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a></li> - <li><a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a></li> - </ol> - +<h2>See also</h2> +<ol> + <li> + <a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a> + </li> + <li> + <a href="{@docRoot}resources/samples/SoftKeyboard/index.html">Soft Keyboard sample</a> + </li> +</ol> </div> </div> - - -<p>To create an input method (IME) for entering text into text fields -and other Views, you need to extend the {@link android.inputmethodservice.InputMethodService}. -class. This class provides much of the basic implementation for an input -method, in terms of managing the state and visibility of the input method and -communicating with the currently visible activity.</p> - -<p>A good starting point would be the SoftKeyboard sample code provided as part -of the SDK. You can modify the sample code to start building your own input -method.</p> - -<p>An input method is packaged like any other application or service. In the -<code>AndroidManifest.xml</code> file, you declare the input method as a -service, with the appropriate intent filter and any associated meta data:</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.fastinput"> - - <application android:label="@string/app_label"><br> - <!-- Declares the input method service --> - <service android:name="FastInputIME" - android:label="@string/fast_input_label" - android:permission="android.permission.BIND_INPUT_METHOD"> - <intent-filter> - <action android:name="android.view.InputMethod" /> - </intent-filter> - <meta-data android:name="android.view.im" android:resource="@xml/method" /> - </service> - - <!-- Optional activities. A good idea to have some user settings. --> - <activity android:name="FastInputIMESettings" android:label="@string/fast_input_settings"> - <intent-filter> - <action android:name="android.intent.action.MAIN"/> - </intent-filter> - </activity> - </application> -</manifest></pre> - -<p>If your input method allows the user to tweak some settings, you should -provide a settings activity that can be launched from the Settings application. -This is optional and you may choose to provide all user settings directly in -your IME's UI.</p> - -<p>The typical life-cycle of an <code>InputMethodService</code> looks like -this:</p> - -<p><img src="images/ime_003.png" style="border: medium none ; width: 374px; height: 871px;"></p> - -<h3>Visual Elements</h3> - -<p>There are two main visual elements for an input method—the input view and the -candidates view. You don't have to follow this style though, if one of them is -not relevant to your input method experience.</p> - -<h4>Input View</h4> - -<p>This is where the user can input text either in the form of keypresses, -handwriting or other gestures. When the input method is displayed for the first -time, <code>InputMethodService.onCreateInputView()</code> will be called. Create -and return the view hierarchy that you would like to display in the input method -window.</p> - -<h4>Candidates View</h4> - -<p>This is where potential word corrections or completions are presented to the -user for selection. Again, this may or may not be relevant to your input method -and you can return <code>null</code> from calls to -<code>InputMethodService.onCreateCandidatesView()</code>, which is the default -behavior.</p> - -<h3>Designing for the different Input Types</h3> - -<p>An application's text fields can have different input types specified on -them, such as free form text, numeric, URL, email address and search. When you -implement a new input method, you need to be aware of the different input types. -Input methods are not automatically switched for different input types and so -you need to support all types in your IME. However, the IME is not responsible -for validating the input sent to the application. That's the responsibility of -the application.</p> - -<p>For example, the LatinIME provided with the Android platform provides -different layouts for text and phone number entry:</p> - -<p><img style="margin: 0pt 10px 0pt 0pt; width: 319px; height: 198px;" src="images/ime_002.png"><img style="width: 320px; height: 199px;" src="images/ime.png"></p> - -<p><code>InputMethodService.onStartInputView()</code> is called with an<code> -EditorInfo</code> object that contains details about the input type and other -attributes of the application's text field.</p><p>(<code>EditorInfo.inputType -& EditorInfo.TYPE_CLASS_MASK</code>) can be one of many different values, -including:</p> - +<p> + An input method editor (IME) is a user control that enables users to enter text. Android + provides an extensible input method framework that allows applications to provide users + alternative input methods, such as on-screen keyboards or even speech input. Once installed, + users can select which IME they want to use from the system settings and use it across the + entire system; only one IME may be enabled at a time. +</p> +<p> + To add an IME to the Android system, you create an Android application + containing a class that extends {@link android.inputmethodservice.InputMethodService}. In + addition, you usually create a "settings" activity that passes options to the IME + service. You can also define a settings UI that's displayed as part of the system settings. +</p> +<p>This article covers the following:</p> <ul> -<li><code>TYPE_CLASS_NUMBER</code></li> -<li><code>TYPE_CLASS_DATETIME</code></li> -<li><code>TYPE_CLASS_PHONE</code></li> -<li><code>TYPE_CLASS_TEXT</code></li> + <li>The IME lifecycle.</li> + <li>Declaring IME components in the application manifest.</li> + <li>The IME API.</li> + <li>Designing an IME UI.</li> + <li>Sending text from an IME to an application.</li> + <li>Working with IME subtypes.</li> </ul> +<p> + If you haven't worked with IMEs before, you should read the introductory article + <a href="{@docRoot}resources/articles/on-screen-inputs.html">Onscreen Input Methods</a> first. + Also, the Soft Keyboard sample app included in the SDK contains sample code that you can modify + to start building your own IME. +</p> +<h2 id="InputMethodLifecycle">The IME Lifecycle</h2> +<p> + The following diagram describes the life cycle of an IME: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_lifecycle_image.png" alt="" height="845" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> The life cycle of an IME. +</p> +<p> + The following sections describe how to implement the UI and code associated with an IME that + follows this lifecycle. +</p> +<h2 id="DefiningIME">Declaring IME Components in the Manifest</h2> +<p> + In the Android system, an IME is an Android application that contains a special IME service. + The application's manifest file must declare the service, request the necessary permissions, + provide an intent filter that matches the action <code>action.view.InputMethod</code>, and + provide metadata that defines characteristics of the IME. In addition, to provide a settings + interface that allows the user to modify the behavior of the IME, you can define a "settings" + activity that can be launched from System Settings. +</p> +<p> + The following snippet declares IME service. It requests the permission {@link + android.Manifest.permission#BIND_INPUT_METHOD} to allow the service to connect the IME to + the system, sets up an intent filter that matches the action + <code>android.view.InputMethod</code>, and defines metadata for the IME: +</p> +<pre> +<!-- Declares the input method service --> + <service android:name="FastInputIME" + android:label="@string/fast_input_label" + android:permission="android.permission.BIND_INPUT_METHOD"> + <intent-filter> + <action android:name="android.view.InputMethod" /> + </intent-filter> + <meta-data android:name="android.view.im" android:resource="@xml/method" /> + </service> +</pre> +<p> + This next snippet declares the settings activity for the IME. It has an intent filter for + {@link android.content.Intent#ACTION_MAIN} that indicates this activity is the main entry point + for the IME application:</p> +<pre> + <!-- Optional: an activity for controlling the IME settings --> + <activity android:name="FastInputIMESettings" + android:label="@string/fast_input_settings"> + <intent-filter> + <action android:name="android.intent.action.MAIN"/> + </intent-filter> + </activity> +</pre> +<p> + You can also provide access to the IME's settings directly from its UI. +</p> +<h2 id="IMEAPI">The Input Method API</h2> +<p> + Classes specific to IMEs are found in the {@link android.inputmethodservice} and {@link + android.view.inputmethod} packages. The {@link android.view.KeyEvent} class is important for + handling keyboard characters. +</p> +<p> + The central part of an IME is a service component, a class that extends + {@link android.inputmethodservice.InputMethodService}. In addition to implementing the + normal service lifecycle, this class has callbacks for providing your IME's UI, handling user + input, and delivering text to the field that currently has focus. By default, the + {@link android.inputmethodservice.InputMethodService} class provides most of the implementation + for managing the state and visibility of the IME and communicating with the current + input field. +</p> +<p> + The following classes are also important: +</p> +<dl> + <dt>{@link android.view.inputmethod.BaseInputConnection}</dt> + <dd> + Defines the communication channel from an {@link android.view.inputmethod.InputMethod} + back to the application that is receiving its input. You use it to read text around the + cursor, commit text to the text box, and send raw key events to the application. + Applications should extend this class rather than implementing the base interface + {@link android.view.inputmethod.InputConnection}. + </dd> + <dt>{@link android.inputmethodservice.KeyboardView}</dt> + <dd> + An extension of {@link android.view.View} that renders a keyboard and responds to user + input events. The keyboard layout is specified by an instance of + {@link android.inputmethodservice.Keyboard}, which you can define in an XML file. + </dd> +</dl> +<h2 id="IMEUI">Designing the Input Method UI</h2> +<p> + There are two main visual elements for an IME: the <strong>input</strong> view and the + <strong>candidates</strong> view. You only have to implement the elements that are relevant to + the input method you're designing. +</p> +<h3 id="InputView">Input view</h3> +<p> + The input view is the UI where the user inputs text, in the form of keyclicks, handwriting or + gestures. When the iIME is displayed for the first time, the system calls the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} callback. In your + implementation of this method, you create the layout you want to display in the IME + window and return the layout to the system. This snippet is an example of implementing the + {@link android.inputmethodservice.InputMethodService#onCreateInputView()} method: +<pre> + @Override + public View onCreateInputView() { + MyKeyboardView inputView = + (MyKeyboardView) getLayoutInflater().inflate( R.layout.input, null); + + inputView.setOnKeyboardActionListener(this); inputView.setKeyboard(mLatinKeyboard); + + return mInputView; + } +</pre> +<p> + In this example, {@code MyKeyboardView} is an instance of a custom implementation of + {@link android.inputmethodservice.KeyboardView} that renders a + {@link android.inputmethodservice.Keyboard}. If you’re building a traditional QWERTY keyboard, + see the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample + app for an example of how to extend the {@link android.inputmethodservice.KeyboardView} class. +</p> +<h3 id="CandidateView">Candidates view</h3> +<p> + The candidates view is the UI where the IME displays potential word corrections or + suggestions for the user to select. In the IME lifecycle, the system calls + {@link android.inputmethodservice.InputMethodService#onCreateCandidatesView()} when it's ready + to display the candidate view. In your implementation of this method, return a layout that shows + word suggestions, or return null if you don’t want to show anything (a null response is the + default behavior, so you don’t have to implement this if you don’t provide suggestions).</p> +<p> + For an example implementation that provides user suggestions, see the + <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample app. +</p> +<h3 id="DesignConsiderations">UI design considerations</h3> +<p> + This section describes some specific UI design considerations for IMEs. +</p> +<h4>Handling multiple screen sizes</h4> +<p> + The UI for your IME must be able to scale for different screen sizes, and it also + must handle both landscape and portrait orientations. In non-fullscreen IME mode, leave + sufficient space for the application to show the text field and any associated context, so that + no more than half the screen is occupied by the IME. In fullscreen IME mode this is not an + issue. +</p> +<h4>Handling different input types</h4> +<p> + Android text fields allow you to set a specific input type, such as free form text, numbers, + URLs, email addresses, and search strings. When you implement a new IME, you need to + detect the input type of each field and provide the appropriate interface for it. However, you + don't have to set up your IME to check that the user entered text that's valid for the + input type; that's the responsibility of the application that owns the text field. +</p> +<p> + For example, here are screenshots of the interfaces that the Latin IME provided with the + Android platform provides for text and phone number inputs: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_text_type_screenshot.png" alt="" + height="142" id="figure2" /> +<img src="{@docRoot}resources/articles/images/inputmethod_numeric_type_screenshot.png" alt="" + height="120" id="figure2a" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Latin IME input types. +</p> +<p> + When an input field receives focus and your IME starts, the system calls + {@link android.inputmethodservice.InputMethodService#onStartInputView(EditorInfo, boolean) + onStartInputView()}, passing in an {@link android.view.inputmethod.EditorInfo} object that + contains details about the input type and other attributes of the text field. In this object, + the {@link android.view.inputmethod.EditorInfo#inputType} field contains the text field's input + type. +</p> +<p> + The {@link android.view.inputmethod.EditorInfo#inputType} field is an <code>int</code> + that contains bit patterns for various input type settings. To test it for the text field's + input type, mask it with the constant {@link android.text.InputType#TYPE_MASK_CLASS}, like + this: +</p> +<pre> +inputType & InputType.TYPE_MASK_CLASS +</pre> +<p> +The input type bit pattern can have one of several values, including: +</p> +<dl> + <dt>{@link android.text.InputType#TYPE_CLASS_NUMBER}</dt> + <dd> + A text field for entering numbers. As illustrated in the previous screen shot, the + Latin IME displays a number pad for fields of this type. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_DATETIME}</dt> + <dd> + A text field for entering a date and time. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_PHONE}</dt> + <dd> + A text field for entering telephone numbers. + </dd> + <dt>{@link android.text.InputType#TYPE_CLASS_TEXT}</dt> + <dd> + A text field for entering all supported characters. + </dd> +</dl> +<p> + These constants are described in more detail in the reference documentation for + {@link android.text.InputType}. +</p> +<p> + The {@link android.view.inputmethod.EditorInfo#inputType} field can contain other bits that + indicate a variant of the text field type, such as: +</p> +<dl> + <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_PASSWORD}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering passwords. The + input method will display dingbats instead of the actual text. + </dd> + <dt>{@link android.text.InputType#TYPE_TEXT_VARIATION_URI}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering web URLs and + other Uniform Resource Identifiers (URIs). + </dd> + <dt>{@link android.text.InputType#TYPE_TEXT_FLAG_AUTO_COMPLETE}</dt> + <dd> + A variant of {@link android.text.InputType#TYPE_CLASS_TEXT} for entering text that the + application "auto-completes" from a dictionary, search, or other facility. + </dd> +</dl> +<p> + Remember to mask {@link android.view.inputmethod.EditorInfo#inputType} with the appropriate + constant when you test for these variants. The available mask constants are listed in the + reference documentation for {@link android.text.InputType}. +</p> +<p class="caution"> + <strong>Caution:</strong> In your own IME, make sure you handle text correctly when you send it + to a password field. Hide the password in your UI both in the input view and in the candidates + view. Also remember that you shouldn't store passwords on a device. To learn more, see the <a + href="{@docRoot}guide/practices/security.html">Designing for Security</a> guide. +</p> +<h2 id="SendText">Sending Text to the Application</h2> +<p> + As the user inputs text with your IME, you can send text to the application by + sending individual key events or by editing the text around the cursor in the application's text + field. In either case, you use an instance of {@link android.view.inputmethod.InputConnection} + to deliver the text. To get this instance, call + {@link android.inputmethodservice.InputMethodService#getCurrentInputConnection + InputMethodService.getCurrentInputConnection()}. +</p> +<h3 id="EditingCursor">Editing the text around the cursor</h3> +<p> + When you're handling the editing of existing text in a text field, some of the more useful + methods in {@link android.view.inputmethod.BaseInputConnection} are: +</p> +<dl> + <dt> + {@link android.view.inputmethod.BaseInputConnection#getTextBeforeCursor(int, int) + getTextBeforeCursor()}</dt> + <dd> + Returns a {@link java.lang.CharSequence} containing the number of requested characters + before the current cursor position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#getTextAfterCursor(int, int) + getTextAfterCursor()} + </dt> + <dd> + Returns a {@link java.lang.CharSequence} containing the number of requested characters + following the current cursor position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#deleteSurroundingText(int, int) + deleteSurroundingText()} + </dt> + <dd> + Deletes the specified number of characters before and following the current cursor + position. + </dd> + <dt> + {@link android.view.inputmethod.BaseInputConnection#commitText(CharSequence, int) + commitText()} + </dt> + <dd> + Commit a {@link java.lang.CharSequence} to the text field and set a new cursor + position. + </dd> +</dl> +<p> + For example, the following snippet shows how to replace the text "Fell" to the left of the + with the text "Hello!": +</p> +<pre> + InputConnection ic = getCurrentInputConnection(); + + ic.deleteSurroundingText(4, 0); + + ic.commitText("Hello", 1); + + ic.commitText("!", 1); +</pre> +<h3 id="ComposeThenCommit">Composing text before committing</h3> +<p> + If your IME does text prediction or requires multiple steps to compose a glyph or + word, you can show the progress in the text field until the user commits the word, and then you + can replace the partial composition with the completed text. You may give special treatment to + the text by adding a "span" to it when you pass it to InputConnection#setComposingText(). +</p> +<p> + The following snippet shows how to show progress in a text field: +</p> +<pre> + InputConnection ic = getCurrentInputConnection(); + + ic.setComposingText("Composi", 1); +... -<p>See <code>android.text.InputType</code> for more details.</p> - -<p><code>EditorInfo.inputType</code> can contain other masked bits that -indicate the class variation and other flags. For example, -<code>TYPE_TEXT_VARIATION_PASSWORD</code> or <code>TYPE_TEXT_VARIATION_URI</code> -or <code>TYPE_TEXT_FLAG_AUTO_COMPLETE</code>.</p> - -<h4>Password fields</h4> - -<p>Pay -specific attention when sending text to password fields. Make sure that -the password is not visible within your UI — neither in the input -view or the candidates view. Also, do not save the password anywhere without -explicitly informing the user.</p> - -<h3>Landscape vs. portrait</h3> - -<p>The UI needs to be able to scale between landscape and portrait orientations. -In non-fullscreen IME mode, leave sufficient space for the application to show -the text field and any associated context. Preferably, no more than half the -screen should be occupied by the IME. In fullscreen IME mode this is not an -issue.</p> - -<h3>Sending text to the application</h3> - -<p>There are two ways to send text to the application. You can either send -individual key events or you can edit the text around the cursor in the -application's text field.</p> - -<p>To send a key event, you can simply construct KeyEvent objects and call -<code>InputConnection.sendKeyEvent()</code>. Here are some examples:</p> - -<pre>InputConnection ic = getCurrentInputConnection(); -long eventTime = SystemClock.uptimeMillis(); -ic.sendKeyEvent(new KeyEvent(eventTime, eventTime, - KeyEvent.ACTION_DOWN, keyEventCode, 0, 0, 0, 0, - KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE)); -ic.sendKeyEvent(new KeyEvent(SystemClock.uptimeMillis(), eventTime, - KeyEvent.ACTION_UP, keyEventCode, 0, 0, 0, 0, - KeyEvent.FLAG_SOFT_KEYBOARD|KeyEvent.FLAG_KEEP_TOUCH_MODE));</pre> - -<p>Or use the convenience method:</p> - -<pre>InputMethodService.sendDownUpKeyEvents(keyEventCode);</pre> - -<p class="note"><strong>Note</strong>: -It is recommended to use the above method for certain fields such as -phone number fields because of filters that may be applied to the text -after each key press. Return key and delete key should also be sent as -raw key events for certain input types, as applications may be watching -for specific key events in order to perform an action.</p> + ic.setComposingText("Composin", 1); -<p>When editing text in a text field, some of the more useful methods on -<code>android.view.inputmethod.InputConnection</code> are:</p> +... + ic.commitText("Composing ", 1); +</pre> +<p> + The following screenshots show how this appears to the user: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_1.png" alt="" height="54" + id="figure3a" /> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_2.png" alt="" height="53" + id="figure3b" /> +<img src="{@docRoot}resources/articles/images/inputmethod_composing_text_3.png" alt="" height="31" + id="figure3c" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Composing text before committing. +</p> +<h3 id="HardwareKeyEvents">Intercepting hardware key events</h3> +<p> + Even though the input method window doesn't have explicit focus, it receives hardware key + events first and can choose to consume them or forward them along to the application. For + example, you may want to consume the directional keys to navigate within your UI for candidate + selection during composition. You may also want to trap the back key to dismiss any popups + originating from the input method window.</p> +<p> + To intercept hardware keys, override + {@link android.inputmethodservice.InputMethodService#onKeyDown(int, KeyEvent) onKeyDown()} + and {@link android.inputmethodservice.InputMethodService#onKeyUp(int, KeyEvent) onKeyUp()}. + See the <a href=”{@docRoot}resources/samples/SoftKeyboard/index.html”>Soft Keyboard</a> sample + app for an example. +</p> +<p> + Remember to call the <code>super()</code> method for keys you don't want to handle yourself. +</p> +<h2 id="IMESubTypes">Creating an IME Subtype</h2> +<p> + Subtypes allow the IME to expose multiple input modes and languages supported by an IME. A + subtype can represent: +</p> <ul> -<li><code>getTextBeforeCursor()</code></li> -<li><code>getTextAfterCursor()</code></li> -<li><code>deleteSurroundingText()</code></li> -<li><code>commitText()</code></li> + <li>A locale such as en_US or fr_FR</li> + <li>An input mode such as voice, keyboard, or handwriting</li> + <li> + Other input styles, forms, or properties specific to the IME, such as 10-key or qwerty + keyboard layouts. + </li> </ul> - -<p>For example, let's say the text "Fell" is to the left of the cursor -and you want to replace it with "Hello!":</p> - -<pre>InputConnection ic = getCurrentInputConnection(); -ic.deleteSurroundingText(4, 0); -ic.commitText("Hello", 1); -ic.commitText("!", 1);</pre> - -<h4>Composing text before committing</h4> - -<p>If your input method does some kind of text prediction or requires multiple -steps to compose a word or glyph, you can show the progress in the text field -until the user commits the word and then you can replace the partial composition -with the completed text. The text that is being composed will be highlighted in -the text field in some fashion, such as an underline.</p> - -<pre>InputConnection ic = getCurrentInputConnection(); -ic.setComposingText("Composi", 1); -... -ic.setComposingText("Composin", 1); -... -ic.commitText("Composing ", 1);</pre> - -<p><img style="width: 320px; height: 98px; margin-bottom: 10px;" src="images/ime_006.png"> -<img style="width: 320px; height: 97px; margin-bottom: 10px;" src="images/ime_005.png"> -<img style="width: 320px; height: 97px;" src="images/ime_004.png"></p> - -<h3>Intercepting hard key events</h3> - -<p>Even though the input method window doesn't have explicit focus, it receives -hard key events first and can choose to consume them or forward them along to -the application. For instance, you may want to consume the directional keys to -navigate within your UI for candidate selection during composition. Or you may -want to trap the back key to dismiss any popups originating from the input -method window. To intercept hard keys, override -<code>InputMethodService.onKeyDown()</code> and -<code>InputMethodService.onKeyUp().</code> Remember to call -<code>super.onKey</code>* if you don't want to consume a certain key -yourself.</p> - -<h3>Other considerations</h3> - +<p> + Basically, the mode can be any text such as "keyboard", "voice", and so forth. +</p> +<p>A subtype can also expose a combination of these.</p> +<p> + Subtype information is used for an IME switcher dialog that's available from the notification + bar and also for IME settings. The information also allows the framework to bring up a + specific subtype of an IME directly. When you build an IME, use the subtype facility, because + it helps the user identify and switch between different IME languages and modes. +</p> +<p> + You define subtypes in one of the input method's XML resource files, using the + <code><subtype></code> element. The following snippet defines an IME with two + subtypes: a keyboard subtype for the US English locale, and another keyboard subtype for the + French language locale for France: +</p> +<pre> +<input-method xmlns:android="http://schemas.android.com/apk/res/android" + android:settingsActivity="com.example.softkeyboard.Settings" + android:icon="@drawable/ime_icon" + <subtype android:name="@string/display_name_english_keyboard_ime" + android:icon="@drawable/subtype_icon_english_keyboard_ime" + android:imeSubtypeLanguage="en_US" + android:imeSubtypeMode="keyboard" + android:imeSubtypeExtraValue="somePrivateOption=true" + /> + <subtype android:name="@string/display_name_french_keyboard_ime" + android:icon="@drawable/subtype_icon_french_keyboard_ime" + android:imeSubtypeLanguage="fr_FR" + android:imeSubtypeMode="keyboard" + android:imeSubtypeExtraValue="foobar=30,someInternalOption=false" + /> + <subtype android:name="@string/display_name_german_keyboard_ime" + ... + /> +/> +</pre> +<p> + To ensure that your subtypes are labeled correctly in the UI, use %s to get a subtype label + that is the same as the subtype’s locale label. This is demonstrated in the next two snippets. + The first snippet shows part of the input method's XML file: +</p> +<pre> + <subtype + android:label="@string/label_subtype_generic" + android:imeSubtypeLocale="en_US" + android:icon="@drawable/icon_en_us" + android:imeSubtypeMode="keyboard" /> +</pre> +<p> + The next snippet is part of the IME's <code>strings.xml</code> file. The string + resource <code>label_subtype_generic</code>, which is used by the input method UI definition to + set the subtype's label, is defined as: +</p> +<pre> +<string name="label_subtype_generic">%s</string> +</pre> +<p> + This sets the subtype’s display name to “English (United States)” in any English language + locale, or to the appropriate localization in other locales. +</p> +<h3 id="SubtypeProcessing">Choosing IME subtypes from the notification bar</h3> +<p> + The Android system manages all subtypes exposed by all IMEs. IME subtypes are + treated as modes of the IME they belong to. In the notification bar, a user can select an + available subtype for the currently-set IME, as shown in the following screenshot: +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_notification.png" alt="" + height="85" id="figure4" /> +<p class="img-caption"> + <strong>Figure 4.</strong> Choosing an IME subtype from the notification bar. +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_preferences.png" alt="" + height="165" id="figure5" /> +<p class="img-caption"> + <strong>Figure 5.</strong> Setting subtype preferences in System Settings. +</p> +<h3 id="SubtypeSettings">Choosing IME subtypes from System Settings</h3> +<p> + A user can control how subtypes are used in the “Language & input” settings panel in the + System Settings area. In the Soft Keyboard sample, the file + <code>InputMethodSettingsFragment.java</code> contains an implementation that + facilitates a subtype enabler in the IME settings. Please refer to the SoftKeyboard sample in + the Android SDK for more information about how to support Input Method Subtypes in your IME. +</p> +<img src="{@docRoot}resources/articles/images/inputmethod_subtype_settings.png" alt="" + height="210" id="figure6" /> +<p class="img-caption"> + <strong>Figure 6.</strong> Choosing a language for the IME. +</p> +<h2 id="GeneralDesign">General IME Considerations</h2> +<p> + Here are some other things to consider as you're implementing your IME: +</p> <ul> -<li>Provide a way for the user to easily bring up any associated settings -directly from the input method UI</li> -<li>Provide -a way for the user to switch to a different input method (multiple -input methods may be installed) directly from the input method UI.</li> -<li>Bring -up the UI quickly - preload or lazy-load any large resources so that -the user sees the input method quickly on tapping on a text field. And -cache any resources and views for subsequent invocations of the input -method.</li> -<li>On the flip side, any large memory allocations should -be released soon after the input method window is hidden so that -applications can have sufficient memory to run. Consider using a -delayed message to release resources if the input method is in a hidden -state for a few seconds.</li> -<li>Make sure that most common characters -can be entered using the input method, as users may use punctuation in -passwords or user names and they shouldn't be stuck in a situation -where they can't enter a certain character in order to gain access into -a password-locked device.</li> +<li> + Provide a way for users to set options directly from the IME's UI. +</li> +<li> + Because multiple IMEs may be installed on the device, provide a way for the user to switch to a + different IME directly from the input method UI. +</li> +<li> + Bring up the IME's UI quickly. Preload or load on demand any large resources so that users + see the IME as soon as they tap on a text field. Cache resources and views for subsequent + invocations of the input method. +</li> +<li> + Conversely, you should release large memory allocations soon after the input method window is + hidden, so that applications can have sufficient memory to run. Consider using a delayed message + to release resources if the IME is in a hidden state for a few seconds. +</li> +<li> + Make sure that users can enter as many characters as possible for the language or locale + associated with the IME. Remember that users may use punctuation in passwords or user + names, so your IME has to provide many different characters to allow users to enter a + password and get access to the device. +</li> </ul> - -<h3>Samples</h3> - -<p>For a real world example, with support for multiple input types and text -prediction, see the <a id="ccpb" -href="http://android.git.kernel.org/?p=platform/packages/inputmethods/LatinIME. -git;a=tree" title="LatinIME source code online">LatinIME source code</a>. The -Android SDK also includes a SoftKeyboard sample as well.</p> diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_1.png b/docs/html/resources/articles/images/inputmethod_composing_text_1.png Binary files differnew file mode 100644 index 0000000..3403489 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_1.png diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_2.png b/docs/html/resources/articles/images/inputmethod_composing_text_2.png Binary files differnew file mode 100644 index 0000000..67bd1d9 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_2.png diff --git a/docs/html/resources/articles/images/inputmethod_composing_text_3.png b/docs/html/resources/articles/images/inputmethod_composing_text_3.png Binary files differnew file mode 100644 index 0000000..4fd1a30 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_composing_text_3.png diff --git a/docs/html/resources/articles/images/inputmethod_lifecycle_image.png b/docs/html/resources/articles/images/inputmethod_lifecycle_image.png Binary files differnew file mode 100644 index 0000000..5f7cf95 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_lifecycle_image.png diff --git a/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png b/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png Binary files differnew file mode 100644 index 0000000..61b7483 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_numeric_type_screenshot.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_notification.png b/docs/html/resources/articles/images/inputmethod_subtype_notification.png Binary files differnew file mode 100644 index 0000000..3f13927 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_notification.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_preferences.png b/docs/html/resources/articles/images/inputmethod_subtype_preferences.png Binary files differnew file mode 100644 index 0000000..d8aa0cf --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_preferences.png diff --git a/docs/html/resources/articles/images/inputmethod_subtype_settings.png b/docs/html/resources/articles/images/inputmethod_subtype_settings.png Binary files differnew file mode 100644 index 0000000..b8942c6 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_subtype_settings.png diff --git a/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png b/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png Binary files differnew file mode 100644 index 0000000..8008b27 --- /dev/null +++ b/docs/html/resources/articles/images/inputmethod_text_type_screenshot.png diff --git a/docs/html/resources/articles/images/spellcheck_client_flow.png b/docs/html/resources/articles/images/spellcheck_client_flow.png Binary files differnew file mode 100644 index 0000000..4e097aa --- /dev/null +++ b/docs/html/resources/articles/images/spellcheck_client_flow.png diff --git a/docs/html/resources/articles/images/spellcheck_lifecycle.png b/docs/html/resources/articles/images/spellcheck_lifecycle.png Binary files differnew file mode 100644 index 0000000..0b10824 --- /dev/null +++ b/docs/html/resources/articles/images/spellcheck_lifecycle.png diff --git a/docs/html/resources/articles/images/textview_spellcheck_screenshot_1.png b/docs/html/resources/articles/images/textview_spellcheck_screenshot_1.png Binary files differnew file mode 100644 index 0000000..deb47c4 --- /dev/null +++ b/docs/html/resources/articles/images/textview_spellcheck_screenshot_1.png diff --git a/docs/html/resources/articles/images/textview_spellcheck_screenshot_2.png b/docs/html/resources/articles/images/textview_spellcheck_screenshot_2.png Binary files differnew file mode 100644 index 0000000..e3af4c5 --- /dev/null +++ b/docs/html/resources/articles/images/textview_spellcheck_screenshot_2.png diff --git a/docs/html/resources/articles/index.jd b/docs/html/resources/articles/index.jd index 220a4ed..2947e4a 100644 --- a/docs/html/resources/articles/index.jd +++ b/docs/html/resources/articles/index.jd @@ -47,7 +47,16 @@ parent.link=../browser.html?tag=article <dt><a href="{@docRoot}resources/articles/glsurfaceview.html">Introducing GLSurfaceView</a></dt> <dd>This article provides an overview of GLSurfaceView, a class that makes it easy to implement 2D or 3D OpenGL rendering inside of an Android application.</dd> </dl> - +<dl> + <dt> + <a href="{@docRoot}resources/articles/spell-checker-framework.jd"> + Using the Spell Checker Framework</a> + </dt> + <dd> + This article describes how to use the Spell Checker Framework to check spelling in + various ways in your application. + </dd> +</dl> <dl> <dt><a href="{@docRoot}resources/articles/layout-tricks-reuse.html">Layout Tricks: Creating Reusable UI Components</a></dt> <dd>Learn how to combine multiple standard UI widgets into a single high-level component, which can be reused throughout your application.</dd> @@ -149,7 +158,7 @@ parent.link=../browser.html?tag=article </dl> <dl> - <dt><a href="{@docRoot}resources/articles/window-bg-speed.html">Window Backgrounds & UI Speed</a></dt> + <dt><a href="{@docRoot}resources/articles/window-bg-speed.html">Window Backgrounds & UI Speed</a></dt> <dd>Some Android applications need to squeeze every bit of performance out of the UI toolkit and there are many ways to do so. In this article, you will discover how to speed up the drawing and the perceived startup time of your activities. Both of these techniques rely on a single feature, the window's background drawable.</dd> </dl> diff --git a/docs/html/resources/articles/live-wallpapers.jd b/docs/html/resources/articles/live-wallpapers.jd index bfbbb34..0692a62 100644 --- a/docs/html/resources/articles/live-wallpapers.jd +++ b/docs/html/resources/articles/live-wallpapers.jd @@ -76,19 +76,19 @@ live wallpapers.</li> supported only on Android 2.1 (API level 7) and higher versions of the platform. To ensure that your application can only be installed on devices that support live wallpapers, remember to add the following to the application's manifest -before publishing to Android Market:</p> +before publishing to Google Play:</p> <ul> <li><code><uses-sdk android:minSdkVersion="7" /></code>, which indicates -to Android Market and the platform that your application requires Android 2.1 or +to Google Play and the platform that your application requires Android 2.1 or higher. For more information, see the <a href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> and the documentation for the <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code><uses-sdk></code></a> element.</li> <li><code><uses-feature android:name="android.software.live_wallpaper" /></code>, -which tells Android Market that your application includes a live wallpaper -Android Market uses this feature as a filter, when presenting users lists of -available applications. When you declaring this feature, Android Market +which tells Google Play that your application includes a live wallpaper +Google Play uses this feature as a filter, when presenting users lists of +available applications. When you declaring this feature, Google Play displays your application only to users whose devices support live wallpapers, while hiding it from other devices on which it would not be able to run. For more information, see the documentation for the @@ -98,5 +98,5 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code element.</li> </ul> -<p>Many great live wallpapers are already available on Android Market and +<p>Many great live wallpapers are already available on Google Play and we can't wait to see more!</p> diff --git a/docs/html/resources/articles/speech-input.jd b/docs/html/resources/articles/speech-input.jd index 0867ff2..2f9cd69 100644 --- a/docs/html/resources/articles/speech-input.jd +++ b/docs/html/resources/articles/speech-input.jd @@ -9,7 +9,7 @@ on. </p> <p>Speech input adds another dimension to staying in touch. Google's Voice Search application, which is pre-installed on many Android devices -and available in Android Market, provides powerful features like "search by voice" +and available on Google Play, provides powerful features like "search by voice" and Voice Actions like "Navigate to." Further enhancing the voice experience, Android 2.1 introduces a <a href="http://www.youtube.com/watch?v=laOlkD8LmZw"> @@ -21,7 +21,7 @@ any context in which you would normally type. </p> <p> We believe speech can fundamentally change the mobile experience. We would like to invite every Android application developer to consider integrating speech input capabilities -via the Android SDK. One of our favorite apps in the Market that integrates +via the Android SDK. One of our favorite apps on Google Play that integrates speech input is <a href="http://www.handcent.com/">Handcent SMS</a>, because you can dictate a reply to any SMS with a quick tap on the SMS popup window. Here is Speech input integrated into diff --git a/docs/html/resources/articles/spell-checker-framework.jd b/docs/html/resources/articles/spell-checker-framework.jd new file mode 100644 index 0000000..8d57b4e --- /dev/null +++ b/docs/html/resources/articles/spell-checker-framework.jd @@ -0,0 +1,236 @@ +page.title=Using the Spell Checker Framework +parent.title=Articles +parent.link=../browser.html?tag=article +@jd:body +<div id="qv-wrapper"> +<div id="qv"> +<h2>In This Document</h2> +<ol> + <li> + <a href="#SpellCheckLifeCycle">Spell Check Lifecycle</a> + </li> + <li> + <a href="#SpellCheckImplementation">Implementing a Spell Checker Service</a> + </li> + <li> + <a href="#SpellCheckClient">Implementing a Spell Checker Client</a> + </li> +</ol> + <h2>See also</h2> + <ol> + <li> + <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> + Spell Checker Service</a> sample app + </li> + <li> + <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app + </li> + </ol> +</div> +</div> + +<p> + The Android platform offers a spell checker framework that lets you implement + and access spell checking in your application. The framework is one of the + Text Service APIs offered by the Android platform. +</p> +<p> + To use the framework in your app, you create a special type of Android service that + generates a spell checker <strong>session</strong> object. Based on text you provide, + the session object returns spelling suggestions generated by the spell checker. +</p> +<h2 id="SpellCheckLifeCycle">Spell Checker Lifecycle</h2> +<p> + The following diagram shows the lifecycle of the spell checker service: +</p> +<img src="{@docRoot}resources/articles/images/spellcheck_lifecycle.png" alt="" height="596" + id="figure1" /> +<p class="img-caption"> + <strong>Figure 1.</strong> The spell checker service lifecycle. +</p> +<p> + To initiate spell checking, your app starts its implementation of the spell checker + service. Clients in your app, such as activities or individual UI elements, request a + spell checker session from the service, then use the session to get suggestions for text. + As a client terminates its operation, it closes its spell checker session. If necessary, your + app can shut down the spell checker service at any time. +</p> +<h2 id="SpellCheckImplementation">Implementing a Spell Checker Service</h2> +<p> + To use the spell checker framework in your app, add a spell checker service component including + the session object definition. You can also add to your app an optional activity that + controls settings. You must also add an XML metadata file that describes + the spell checker service, and add the appropriate elements to your manifest file. +</p> +<h3 id="SpellCheckCode">Spell checker classes</h3> +<p> + Define the service and session object with the following classes: +</p> +<dl> + <dt> + A subclass of {@link android.service.textservice.SpellCheckerService} + </dt> + <dd> + The {@link android.service.textservice.SpellCheckerService} implements both the + {@link android.app.Service} class and the spell checker framework interface. Within your + subclass, you must implement the following method: + <dl> + <dt>{@link android.service.textservice.SpellCheckerService#createSession()}</dt> + <dd> + A factory method that returns a + {@link android.service.textservice.SpellCheckerService.Session} object to a + client that wants to do spell checking. + </dd> + </dl> + <p> + See the + <a href="{@docRoot}resources/samples/SpellChecker/SampleSpellCheckerService/index.html"> + Spell Checker Service</a> sample app to learn more about implementing this class. + </p> + </dd> + <dt> + An implementation of {@link android.service.textservice.SpellCheckerService.Session} + </dt> + <dd> + An object that the spell checker service provides to clients, to let them pass text to + the spell checker and receive suggestions. Within this class, you must implement the + following methods: + <dl> + <dt> + {@link android.service.textservice.SpellCheckerService.Session#onCreate()} + </dt> + <dd> + Called by the system in response to + {@link android.service.textservice.SpellCheckerService#createSession()}. In this + method, you can initialize the + {@link android.service.textservice.SpellCheckerService.Session} object based on + the current locale and so forth. + </dd> + <dt> + {@link android.service.textservice.SpellCheckerService.Session#onGetSuggestions(TextInfo, int) + onGetSuggestions()} + </dt> + <dd> + Does the actual spell checking. This method returns an object containing + suggestions for the text passed to it. + </dd> + </dl> + <p> + Optionally, you can implement + {@link android.service.textservice.SpellCheckerService.Session#onCancel()}, which + handles requests to cancel spell checking, or +{@link android.service.textservice.SpellCheckerService.Session#onGetSuggestionsMultiple(TextInfo[], int, boolean) +onGetSuggestionsMultiple()}, which handles batches of suggestion requests, or both. + </p> + <p> + See the + <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app to learn more about implementing this class. + </p> + </dd> +</dl> +<p class="note"> + <strong>Note:</strong> You must implement all aspects of spell checking as asynchronous and + thread-safe. A spell checker may be called simultaneously by different threads running on + different cores. The {@link android.service.textservice.SpellCheckerService} and + {@link android.service.textservice.SpellCheckerService.Session} take care of this + automatically. +</p> +<h3 id="SpellCheckXML">Spell checker manifest and metadata</h3> +<p> + In addition to code, you need to provide the appropriate manifest file and a metadata file for + the spell checker. +</p> +<p> + The manifest file defines the application, the service, and the activity for controlling + settings, as shown in the following snippet: +</p> +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + package="com.example.android.samplespellcheckerservice" > + <application + android:label="@string/app_name" > + <service + android:label="@string/app_name" + android:name=".SampleSpellCheckerService" + android:permission="android.permission.BIND_TEXT_SERVICE" > + <intent-filter > + <action android:name="android.service.textservice.SpellCheckerService" /> + </intent-filter> + + <meta-data + android:name="android.view.textservice.scs" + android:resource="@xml/spellchecker" /> + </service> + + <activity + android:label="@string/sample_settings" + android:name="SpellCheckerSettingsActivity" > + <intent-filter > + <action android:name="android.intent.action.MAIN" /> + </intent-filter> + </activity> + </application> +</manifest> +</pre> +<p> + Notice that components that want to use the service must request the permission + {@link android.Manifest.permission#BIND_TEXT_SERVICE} to ensure that only the system binds to + the service. The service's definition also specifies the <code>spellchecker.xml</code> metadata + file, which is described in the next section. +</p> +<p> + The metadata file <code>spellchecker.xml</code> contains the following XML: +</p> +<pre> +<spell-checker xmlns:android="http://schemas.android.com/apk/res/android" + android:label="@string/spellchecker_name" + android:settingsActivity="com.example.SpellCheckerSettingsActivity"> + <subtype + android:label="@string/subtype_generic" + android:subtypeLocale="en” + /> + <subtype + android:label="@string/subtype_generic" + android:subtypeLocale="fr” + /> +</spell-checker> +</pre> +<p> + The metadata specifies the activity that the spell checker uses for controlling settings. It + also defines subtypes for the spell checker; in this case, the subtypes define locales that + the spell checker can handle. +</p> + + +<!-- Accessing the Spell Checker Service from a Client --> +<h2 id="SpellCheckClient">Accessing the Spell Checker Service from a Client</h2> +<p> + Applications that use {@link android.widget.TextView} views automatically benefit from spell + checking, because {@link android.widget.TextView} automatically uses a spell checker. The + following screenshots show this: +</p> +<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_1.png" alt="" + height="45" id="figure2a" /> +<br> +<img src="{@docRoot}resources/articles/images/textview_spellcheck_screenshot_2.png" alt="" + height="121" id="figure2b" /> +<p class="img-caption"> + <strong>Figure 2.</strong> Spell checking in TextView. +</p> +<p> + However, you may want to interact directly with a spell checker service in other cases as well. + The following diagram shows the flow of control for interacting with a spell checker service: +</p> +<img src="{@docRoot}resources/articles/images/spellcheck_client_flow.png" alt="" + height="394" id="figure3" /> +<p class="img-caption"> + <strong>Figure 3.</strong> Interacting with a spell checker service. +</p> +<p> + The <a href="{@docRoot}resources/samples/SpellChecker/HelloSpellChecker/index.html"> + Spell Checker Client</a> sample app shows how to interact with a spell checker service. The + LatinIME input method editor in the Android Open Source Project also contains an example of + spell checking. +</p>
\ No newline at end of file diff --git a/docs/html/resources/articles/tts.jd b/docs/html/resources/articles/tts.jd index 7d07a89..929d084 100644 --- a/docs/html/resources/articles/tts.jd +++ b/docs/html/resources/articles/tts.jd @@ -43,7 +43,7 @@ our know to install the data that's required for the device to become a multi-lingual talking machine! Downloading and installing the data is accomplished by firing off the ACTION_INSTALL_TTS_DATA intent, which will take -the user to Android Market, and will let her/him initiate the download. +the user to Google Play, and will let her/him initiate the download. Installation of the data will happen automatically once the download completes. Here is an example of what your implementation of <code>onActivityResult()</code> would look like:</p> diff --git a/docs/html/resources/articles/ui-1.6.jd b/docs/html/resources/articles/ui-1.6.jd index 09108dd..b3238e3 100644 --- a/docs/html/resources/articles/ui-1.6.jd +++ b/docs/html/resources/articles/ui-1.6.jd @@ -129,4 +129,4 @@ leaving you more time to concentrate on your application.</p> <p>The Android team is committed to helping you write applications in the easiest and most efficient way possible. We hope you find these improvements -useful and we're excited to see your applications on Android Market.</p> +useful and we're excited to see your applications on Google Play.</p> diff --git a/docs/html/resources/community-groups.jd b/docs/html/resources/community-groups.jd index 599c4ae..6bd347c 100644 --- a/docs/html/resources/community-groups.jd +++ b/docs/html/resources/community-groups.jd @@ -14,7 +14,7 @@ page.title=Developer Forums <li><a href="#UsingEmail">Using email with the mailing lists</a></li> <li><a href="#ApplicationDeveloperLists">Application developer mailing lists</a></li> </ol></li> - <li><a href="#MarketHelp">Android Market Help Forum</a></li> + <li><a href="#PlayHelp">Google Play Help Forum</a></li> </ol> </div> @@ -113,8 +113,8 @@ A low-volume group for security-related announcements by the Android Security Te </ul> -<h2 id="MarketHelp">Android Market Help Forum</h2> +<h2 id="PlayHelp">Google Play Help Forum</h2> -<p>The <a href="http://www.google.com/support/forum/p/Android+Market">Android Market Help Forum</a> is a web-based discussion forum where you can ask questions or report issues relating to Android Market.</p> +<p>The <a href="http://support.google.com/googleplay">Google Play Help Forum</a> is a web-based discussion forum where you can ask questions or report issues relating to Google Play.</p> -<p style="margin-left: 2em"><a href="http://www.google.com/support/forum/p/Android+Market">http://www.google.com/support/forum/p/Android+Market</a></p> +<p style="margin-left: 2em"><a href="http://support.google.com/googleplay">http://support.google.com/googleplay</a></p> diff --git a/docs/html/resources/dashboard/opengl.jd b/docs/html/resources/dashboard/opengl.jd index d55ab2b..4c55522 100644 --- a/docs/html/resources/dashboard/opengl.jd +++ b/docs/html/resources/dashboard/opengl.jd @@ -50,14 +50,14 @@ href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code uses.</p> <p class="note"><strong>Note:</strong> This data is based on the number -of Android devices that have accessed Android Market within a 7-day period +of Android devices that have accessed Google Play within a 7-day period ending on the data collection date noted below.</p> <div class="dashboard-panel"> <img alt="" width="400" height="250" -src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=GL%201.1%20only|GL%202.0%20%26%201.1&chd=t%3A10.7,89.3" /> +src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=GL%201.1%20only|GL%202.0%20%26%201.1&chd=t%3A11.9,88.1" /> <table> <tr> @@ -66,14 +66,14 @@ src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl= </tr> <tr> <td>1.1 only</th> -<td>10.7%</td> +<td>11.9%</td> </tr> <tr> <td>2.0 & 1.1</th> -<td>89.3%</td> +<td>88.1%</td> </tr> </table> -<p><em>Data collected during a 7-day period ending on February 1, 2012</em></p> +<p><em>Data collected during a 7-day period ending on April 2, 2012</em></p> </div> diff --git a/docs/html/resources/dashboard/platform-versions.jd b/docs/html/resources/dashboard/platform-versions.jd index 4ea52af..2cbbe99 100644 --- a/docs/html/resources/dashboard/platform-versions.jd +++ b/docs/html/resources/dashboard/platform-versions.jd @@ -47,12 +47,12 @@ platform version, see <a href="{@docRoot}guide/appendix/api-levels.html">API Lev <h3 id="Current">Current Distribution</h3> <p>The following pie chart and table is based on the number of Android devices that have accessed -Android Market within a 14-day period ending on the data collection date noted below.</p> +Google Play within a 14-day period ending on the data collection date noted below.</p> <div class="dashboard-panel"> <img alt="" height="250" width="470" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.6,1.0,7.6,27.8,0.5,58.1,0.1,1.4,1.9,0.3,0.7&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0|Android%203.1|Android%203.2|Android%204.0|Android%204.0.3&chco=c4df9b,6fad0c" /> +src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.3,0.7,6.0,23.1,0.5,63.2,0.1,1.0,2.2,0.5,2.4&chl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3|Android%202.3.3|Android%203.0|Android%203.1|Android%203.2|Android%204.0|Android%204.0.3&chco=c4df9b,6fad0c" /> <table> <tr> @@ -61,25 +61,25 @@ src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.6,1.0,7.6,27. <th>API Level</th> <th>Distribution</th> </tr> -<tr><td><a href="{@docRoot}sdk/android-1.5.html">Android 1.5</a></td><td>Cupcake</td> <td>3</td><td>0.6%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-1.6.html">Android 1.6</a></td><td>Donut</td> <td>4</td><td>1.0%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-2.1.html">Android 2.1</a></td><td>Eclair</td> <td>7</td><td>7.6%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-2.2.html">Android 2.2</a></td><td>Froyo</td> <td>8</td><td>27.8%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-1.5.html">Android 1.5</a></td><td>Cupcake</td> <td>3</td><td>0.3%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-1.6.html">Android 1.6</a></td><td>Donut</td> <td>4</td><td>0.7%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-2.1.html">Android 2.1</a></td><td>Eclair</td> <td>7</td><td>6.0%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-2.2.html">Android 2.2</a></td><td>Froyo</td> <td>8</td><td>23.1%</td></tr> <tr><td><a href="{@docRoot}sdk/android-2.3.html">Android 2.3 -<br/> Android 2.3.2</a></td><td rowspan="2">Gingerbread</td> <td>9</td><td>0.5%</td></tr> <tr><td><a href="{@docRoot}sdk/android-2.3.3.html">Android 2.3.3 -<br/> - Android 2.3.7</a></td><!-- Gingerbread --> <td>10</td><td>58.1%</td></tr> + Android 2.3.7</a></td><!-- Gingerbread --> <td>10</td><td>63.2%</td></tr> <tr><td><a href="{@docRoot}sdk/android-3.0.html">Android 3.0</a></td> <td rowspan="3">Honeycomb</td> <td>11</td><td>0.1%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-3.1.html">Android 3.1</a></td><!-- Honeycomb --><td>12</td><td>1.4%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td><!-- Honeycomb --><td>13</td><td>1.9%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-3.1.html">Android 3.1</a></td><!-- Honeycomb --><td>12</td><td>1.0%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td><!-- Honeycomb --><td>13</td><td>2.2%</td></tr> <tr><td><a href="{@docRoot}sdk/android-4.0.html">Android 4.0 -<br/> Android 4.0.2</a></td> - <td rowspan="2">Ice Cream Sandwich</td><td>14</td><td>0.3%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td><!-- ICS --><td>15</td><td>0.7%</td></tr> + <td rowspan="2">Ice Cream Sandwich</td><td>14</td><td>0.5%</td></tr> +<tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td><!-- ICS --><td>15</td><td>2.4%</td></tr> </table> -<p><em>Data collected during a 14-day period ending on February 1, 2012</em></p> +<p><em>Data collected during a 14-day period ending on April 2, 2012</em></p> <!-- <p style="font-size:.9em">* <em>Other: 0.1% of devices running obsolete versions</em></p> --> @@ -103,14 +103,14 @@ then it is currently compatible with the percentage of devices indicated on the line for that version meets the y-axis on the right.</p> <p>Each dataset in the timeline is based on the number of Android devices that accessed -Android Market within a 14-day period ending on the date indicated on the x-axis.</p> +Google Play within a 14-day period ending on the date indicated on the x-axis.</p> <div class="dashboard-panel"> <img alt="" height="250" width="660" style="padding:5px;background:#fff" -src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C08/01%7C08/15%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C1%3A%7C2011%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C2012%7C%7C2012%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:98.2,98.1,97.9,97.9,97.7,97.6,97.5,99.4,99.4,99.2,98.6,98.4,98.5|96.9,96.9,96.9,96.9,96.6,96.6,96.5,98.6,98.6,98.5,98.0,97.8,97.9|94.9,95.0,95.1,95.2,95.1,95.4,95.2,97.2,97.3,97.3,96.9,96.8,96.9|79.6,80.5,81.8,82.7,83.3,84.4,84.6,87.0,87.7,88.1,88.4,88.8,89.2|23.7,26.9,30.6,34.1,37.8,40.8,43.5,48.4,52.4,55.2,57.9,59.7,61.3|0.0,0.0,0.0,0.0,0.0,0.0,0.0,2.0,2.3,2.6,3.2,3.2,3.3|0.0,0.0,0.0,0.0,0.0,0.0,0.0,1.0,1.2,1.3,1.7,1.8,1.9&chm=b,c3df9b,0,1,0|b,b6dc7d,1,2,0|tAndroid%202.1,5b831d,2,0,15,,t::-5|b,aadb5e,2,3,0|tAndroid%202.2,496c13,3,0,15,,t::-5|b,9ddb3d,3,4,0|tAndroid%202.3.3,38540b,4,0,15,,t::-5|b,91da1e,4,5,0|b,80c414,5,6,0|B,6fad0c,6,7,0&chg=7,25&chdl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3.3|Android%203.1|Android%203.2&chco=add274,a0d155,94d134,84c323,73ad18,62960f,507d08" /> +src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C02/15%7C03/01%7C03/15%7C04/01%7C1%3A%7C2011%7C%7C%7C%7C%7C%7C2012%7C%7C%7C%7C%7C%7C2012%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:97.7,97.6,97.5,99.4,99.4,99.2,98.9,98.8,99.2,98.9,98.9,99.0,98.8|96.6,96.6,96.5,98.6,98.6,98.5,98.3,98.2,98.6,98.4,98.4,98.6,98.5|95.1,95.4,95.2,97.2,97.3,97.3,97.2,97.2,97.6,97.5,97.6,97.8,97.8|83.3,84.4,84.6,87.0,87.7,88.1,88.7,89.2,89.9,90.3,90.8,91.4,91.8|37.8,40.8,43.5,48.4,52.4,55.2,58.2,60.1,62.0,63.7,65.2,66.8,68.6|0.0,0.0,0.0,2.0,2.3,2.6,3.5,3.6,4.0,4.1,4.3,4.6,5.5|0.0,0.0,0.0,1.0,1.2,1.3,2.0,2.2,2.6,3.0,3.2,3.5,4.5|0.0,0.0,0.0,0.0,0.0,0.0,0.3,0.4,0.7,0.8,1.1,1.3,2.3&chm=b,c3df9b,0,1,0|b,b8dc82,1,2,0|tAndroid%202.1,608920,2,0,15,,t::-5|b,addb67,2,3,0|tAndroid%202.2,517617,3,0,15,,t::-5|b,a3db4b,3,4,0|tAndroid%202.3.3,426210,4,0,15,,t::-5|b,98dc2e,4,5,0|b,8cd41b,5,6,0|b,7ec113,6,7,0|B,6fad0c,7,8,0&chg=7,25&chdl=Android%201.5|Android%201.6|Android%202.1|Android%202.2|Android%202.3.3|Android%203.1|Android%203.2|Android%204.0.3&chco=add274,a2d15a,97d13e,8bcb28,7dba1e,6ea715,5f920e,507d08" /> -<p><em>Last historical dataset collected during a 14-day period ending on February 1, 2012</em></p> +<p><em>Last historical dataset collected during a 14-day period ending on April 2, 2012</em></p> </div><!-- end dashboard-panel --> diff --git a/docs/html/resources/dashboard/screens.jd b/docs/html/resources/dashboard/screens.jd index ae5cdc7..e5c79a1 100644 --- a/docs/html/resources/dashboard/screens.jd +++ b/docs/html/resources/dashboard/screens.jd @@ -53,14 +53,14 @@ application, see <a href="{@docRoot}guide/practices/screens_support.html">Suppor Screens</a>.</p> <p class="note"><strong>Note:</strong> This data is based on the number -of Android devices that have accessed Android Market within a 7-day period +of Android devices that have accessed Google Play within a 7-day period ending on the data collection date noted below.</p> <div class="dashboard-panel"> <img alt="" width="400" height="250" -src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=Xlarge%20/%20mdpi|Large%20/%20ldpi|Large%20/%20mdpi|Normal%20/%20hdpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20xhdpi|Small%20/%20hdpi|Small%20/%20ldpi&chd=t%3A4.8,0.2,2.9,67.1,0.7,18.4,1.8,2.5,1.6" /> +src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl=Xlarge%20/%20mdpi|Large%20/%20ldpi|Large%20/%20mdpi|Normal%20/%20hdpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20xhdpi|Small%20/%20hdpi|Small%20/%20ldpi&chd=t%3A5.8,0.2,2.3,64.6,0.7,19.6,2.4,2.5,1.9" /> <table> <tr> @@ -71,31 +71,31 @@ src="http://chart.googleapis.com/chart?cht=p&chs=400x250&chco=c4df9b,6fad0c&chl= <th scope="col">xhdpi</th> </tr> <tr><th scope="row">small</th> -<td>1.6%</td> <!-- small/ldpi --> +<td>1.9%</td> <!-- small/ldpi --> <td></td> <!-- small/mdpi --> <td>2.5%</td> <!-- small/hdpi --> <td></td> <!-- small/xhdpi --> </tr> <tr><th scope="row">normal</th> <td>0.7%</td> <!-- normal/ldpi --> -<td>18.4%</td> <!-- normal/mdpi --> -<td>67.1%</td> <!-- normal/hdpi --> -<td>1.8%</td> <!-- normal/xhdpi --> +<td>19.6%</td> <!-- normal/mdpi --> +<td>64.6%</td> <!-- normal/hdpi --> +<td>2.4%</td> <!-- normal/xhdpi --> </tr> <tr><th scope="row">large</th> <td>0.2%</td> <!-- large/ldpi --> -<td>2.9%</td> <!-- large/mdpi --> +<td>2.3%</td> <!-- large/mdpi --> <td></td> <!-- large/hdpi --> <td></td> <!-- large/xhdpi --> </tr> <tr><th scope="row">xlarge</th> <td></td> <!-- xlarge/ldpi --> -<td>4.8%</td> <!-- xlarge/mdpi --> +<td>5.8%</td> <!-- xlarge/mdpi --> <td></td> <!-- xlarge/hdpi --> <td></td> <!-- xlarge/xhdpi --> </tr> </table> -<p><em>Data collected during a 7-day period ending on February 1, 2012</em></p> +<p><em>Data collected during a 7-day period ending on April 2, 2012</em></p> </div> diff --git a/docs/html/resources/resources-data.js b/docs/html/resources/resources-data.js index 8ad970b..fb4225d 100644 --- a/docs/html/resources/resources-data.js +++ b/docs/html/resources/resources-data.js @@ -263,6 +263,17 @@ var ANDROID_RESOURCES = [ } }, { + tags: ['article', 'input', 'ui'], + path: 'articles/spell-checker-framework.html', + title: { + en: 'The Android Spell Checker Framework' + }, + description: { + en: 'This article describes the Android spell checker framework and how to use to implement spell checking in applications.' + } + }, + + { tags: ['article', 'ui'], path: 'articles/touch-mode.html', title: { @@ -548,6 +559,16 @@ var ANDROID_RESOURCES = [ } }, { + tags: ['sample', 'new'], + path: 'samples/KeyChainDemo/index.html', + title: { + en: 'KeyChain Demo' + }, + description: { + en: 'A demo application to demonstrate how to use KeyChain APIs.' + } + }, + { tags: ['sample', 'gamedev', 'media'], path: 'samples/LunarLander/index.html', title: { diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs index 8483037..5297c23 100644 --- a/docs/html/resources/resources_toc.cs +++ b/docs/html/resources/resources_toc.cs @@ -97,6 +97,52 @@ </li> </ul> </li> + + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/efficient-downloads/index.html"> + <span class="en">Transferring Data Without Draining the Battery<span +class="new"> new!</span></span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/efficient-network-access.html"> + <span class="en">Optimizing Downloads for Efficient Network Access</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/regular_updates.html"> + <span class="en">Minimizing the Effect of Regular Updates</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/redundant_redundant.html"> + <span class="en">Redundant Downloads are Redundant</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/efficient-downloads/connectivity_patterns.html"> + <span class="en">Modifying Patterns Based on the Connectivity Type</span> + </a> + </li> + </ul> + </li> + + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/search/index.html"> + <span class="en">Adding Search Functionality<span class="new"> new!</span></span> + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>training/search/setup.html"> + <span class="en">Setting up the Search Interface</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/search/search.html"> + <span class="en">Storing and Searching for Data</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/search/backward-compat.html"> + <span class="en">Remaining Backward Compatible</span> + </a> + </li> + </ul> + </li> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>training/id-auth/index.html"> @@ -232,7 +278,69 @@ </a> </li> </ul> + </li> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/tv/index.html"> + <span class="en">Designing for TV<span class="new"> new!</span></span> + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>training/tv/optimizing-layouts-tv.html"> + <span class="en">Optimizing Layouts for TV</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/tv/optimizing-navigation-tv.html"> + <span class="en">Optimizing Navigation for TV</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/tv/unsupported-features-tv.html"> + <span class="en">Handling Features Not Supported on TV</span> + </a> + </li> + </ul> </li> + + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/displaying-bitmaps/index.html"> + <span class="en">Displaying Bitmaps Efficiently<span class="new"> new!</span></span> + </a> + </div> + <ul> + <li><a href="<?cs var:toroot ?>training/displaying-bitmaps/load-bitmap.html"> + <span class="en">Loading Large Bitmaps Efficiently</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/displaying-bitmaps/process-bitmap.html"> + <span class="en">Processing Bitmaps Off the UI Thread</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/displaying-bitmaps/cache-bitmap.html"> + <span class="en">Caching Bitmaps</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/displaying-bitmaps/display-bitmap.html"> + <span class="en">Displaying Bitmaps in Your UI</span> + </a> + </li> + </ul> + </li> + + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>training/accessibility/index.html"> + <span class="en">Implementing Accessibility<span class="new"> new!</span></span> + </a></div> + <ul> + <li><a href="<?cs var:toroot ?>training/accessibility/accessible-app.html"> + <span class="en">Developing Accessible Applications</span> + </a> + </li> + <li><a href="<?cs var:toroot ?>training/accessibility/service.html"> + <span class="en">Developing Accessibility Services</span> + </a> + </li> + </ul> + </li> + </ul> </li> diff --git a/docs/html/resources/samples/get.jd b/docs/html/resources/samples/get.jd index 86ec836..751965f 100644 --- a/docs/html/resources/samples/get.jd +++ b/docs/html/resources/samples/get.jd @@ -26,15 +26,15 @@ needed!</p> <p>The SDK sample code is available to you as a set of downloadable SDK components, each of which contains the samples for a specific Android platform version. Once you have installed the SDK, you can download one or more samples -component(s) into your SDK environment using the Android SDK and AVD Manager +component(s) into your SDK environment using the Android SDK Manager tool, which is pre-installed in the SDK. </p> -<p>To download the samples, launch the Android SDK and AVD Manager tool and +<p>To download the samples, launch the Android SDK Manager tool and select one of the samples components from the <strong>Available Packages</strong> panel, for example "Samples for SDK API 7". Select <strong>Install Selected</strong>, verify and accept the download, then select <strong>Install Accepted</strong> to download the component into your SDK. If -you aren't familiar with the Android SDK and AVD Manager and how to launch or +you aren't familiar with the Android SDK Manager and how to launch or use it, please read the <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> document. </p> @@ -74,7 +74,7 @@ From there you can read a short summary of each sample application and what types of concepts, features, or APIs it includes. Then, use the links provided to move through the directories and files of each sample. The browseable source is generated from the same source code that is downloadable through the Android -SDK and AVD Manager, as described above. </p> +SDK Manager, as described above. </p> <p>The browseable samples files are available online, at the Android Developers site only and are not included in the downloadable offline documentation. diff --git a/docs/html/resources/samples/images/KeyChainDemo1.png b/docs/html/resources/samples/images/KeyChainDemo1.png Binary files differnew file mode 100644 index 0000000..d426c22 --- /dev/null +++ b/docs/html/resources/samples/images/KeyChainDemo1.png diff --git a/docs/html/resources/samples/images/KeyChainDemo2.png b/docs/html/resources/samples/images/KeyChainDemo2.png Binary files differnew file mode 100755 index 0000000..e181e58 --- /dev/null +++ b/docs/html/resources/samples/images/KeyChainDemo2.png diff --git a/docs/html/resources/samples/images/KeyChainDemo3.png b/docs/html/resources/samples/images/KeyChainDemo3.png Binary files differnew file mode 100755 index 0000000..acfdd89 --- /dev/null +++ b/docs/html/resources/samples/images/KeyChainDemo3.png diff --git a/docs/html/resources/samples/images/KeyChainDemo4.png b/docs/html/resources/samples/images/KeyChainDemo4.png Binary files differnew file mode 100755 index 0000000..a9101ab --- /dev/null +++ b/docs/html/resources/samples/images/KeyChainDemo4.png diff --git a/docs/html/resources/tutorials/hello-world.jd b/docs/html/resources/tutorials/hello-world.jd index cc8cb3e..70ba06c 100644 --- a/docs/html/resources/tutorials/hello-world.jd +++ b/docs/html/resources/tutorials/hello-world.jd @@ -42,7 +42,7 @@ you need to do it now.</p> <ol> - <li>In the Android SDK and AVD Manager, choose <strong>Available + <li>In the Android SDK Manager, choose <strong>Available Packages</strong> in the left panel.</li> <li>In the right panel, expand the Android Repository list to display @@ -72,7 +72,7 @@ device settings used by the emulator.</p> <p>To create an AVD:</p> <ol> - <li>In Eclipse, select <strong>Window > Android SDK and AVD Manager</strong>.</li> + <li>In Eclipse, select <strong>Window > AVD Manager</strong>.</li> <li>Select <strong>Virtual Devices</strong> in the left panel.</li> <li>Click <strong>New...</strong>. diff --git a/docs/html/resources/tutorials/notepad/notepad-ex2.jd b/docs/html/resources/tutorials/notepad/notepad-ex2.jd index ed06778..1334d7a 100644 --- a/docs/html/resources/tutorials/notepad/notepad-ex2.jd +++ b/docs/html/resources/tutorials/notepad/notepad-ex2.jd @@ -87,7 +87,7 @@ Open the Notepadv2 class.</p> menu callback used for the options menu. Here, we add just one line, which will add a menu item to delete a note. Call <code>menu.add()</code> like so: <pre> -public void onCreateContextMenu(Menu menu, View v, ContextMenuInfo menuInfo) { +public void onCreateContextMenu(ContextMenu menu, View v, ContextMenuInfo menuInfo) { super.onCreateContextMenu(menu, v, menuInfo); menu.add(0, DELETE_ID, 0, R.string.menu_delete); }</pre> diff --git a/docs/html/resources/tutorials/testing/activity_test.jd b/docs/html/resources/tutorials/testing/activity_test.jd index 4b861e2..f88b768 100644 --- a/docs/html/resources/tutorials/testing/activity_test.jd +++ b/docs/html/resources/tutorials/testing/activity_test.jd @@ -163,7 +163,7 @@ parent.link=../../browser.html?tag=tutorial open the Android SDK and AVD Manager and check in the <strong>Installed Packages</strong> panel. If aren't sure how to download a platform into your SDK, - read <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. + read <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>. </p> </li> </ul> diff --git a/docs/html/resources/tutorials/views/hello-formstuff.jd b/docs/html/resources/tutorials/views/hello-formstuff.jd index b9f6c16..1ddd1df 100644 --- a/docs/html/resources/tutorials/views/hello-formstuff.jd +++ b/docs/html/resources/tutorials/views/hello-formstuff.jd @@ -91,31 +91,30 @@ android.widget.Button} element: android:layout_width="wrap_content" android:layout_height="wrap_content" android:padding="10dp" - android:background="@drawable/android_button" /> + android:background="@drawable/android_button" + android:onClick="onButtonClicked"/> </pre> <p>The <code>android:background</code> attribute specifies the drawable resource to use for the button background (which, when saved at <code>res/drawable/android.xml</code>, is referenced as <code>@drawable/android</code>). This replaces the normal background image -used for buttons throughout the system. In order for the drawable to change its image based on -the button state, the image must be applied to the background.</p> +applied by the system with the drawable created above, which changes its image based on +the button state.</p> + <p>The attribute <code>android:onClick</code> specifies the name of a method in your activity +that the system should call when the user clicks the button. You'll create that method next.</p> </li> <li>To make the button do something when pressed, add the following -code at the end of the {@link android.app.Activity#onCreate(Bundle) onCreate()} method: +method inside your {@link android.app.Activity} class: <pre> -final Button button = (Button) findViewById(R.id.button); -button.setOnClickListener(new OnClickListener() { - public void onClick(View v) { - // Perform action on clicks - Toast.makeText(HelloFormStuff.this, "Beep Bop", Toast.LENGTH_SHORT).show(); - } -}); +public void onButtonClicked(View v) { + // Do something when the button is clicked + Toast.makeText(HelloFormStuff.this, "Button clicked", Toast.LENGTH_SHORT).show(); +} </pre> -<p>This captures the {@link android.widget.Button} from the layout, then adds an {@link -android.view.View.OnClickListener}. The {@link android.view.View.OnClickListener} -must implement the {@link android.view.View.OnClickListener#onClick(View)} callback method, which -defines the action to be made when the button is clicked. In this example, a -{@link android.widget.Toast} message will be displayed.</p> +<p>When you specify this kind of method, which is used in your layout file with the {@code +android:onClick} attribute, the method must be <code>public</code>, have a <code>void</code> return +value, and accept a single {@code android.view.View} parameter. When the system calls this method, +it passes the {@code android.view.View} that was clicked.</p> </li> <li>Now run the application.</li> </ol> @@ -183,34 +182,33 @@ element (inside the {@link android.widget.LinearLayout}): <CheckBox android:id="@+id/checkbox" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="check it out" /> + android:text="check it out" + android:onClick="onCheckboxClicked"/> </pre> + <p>The attribute <code>android:onClick</code> specifies the name of a method in your activity +that the system should call when the user clicks the check box. You'll create that method next.</p> </li> -<li>To do something when the state is changed, add the following code -to the end of the {@link android.app.Activity#onCreate(Bundle) onCreate()} method: +<li>To do something when the state is changed, add the following method inside your {@link +android.app.Activity} class:</p> + <pre> -final CheckBox checkbox = (CheckBox) findViewById(R.id.checkbox); -checkbox.setOnClickListener(new OnClickListener() { - public void onClick(View v) { - // Perform action on clicks, depending on whether it's now checked - if (((CheckBox) v).isChecked()) { - Toast.makeText(HelloFormStuff.this, "Selected", Toast.LENGTH_SHORT).show(); - } else { - Toast.makeText(HelloFormStuff.this, "Not selected", Toast.LENGTH_SHORT).show(); - } +public void onCheckboxClicked(View v) { + // Perform action on clicks, depending on whether it's now checked + if (((CheckBox) v).isChecked()) { + Toast.makeText(HelloFormStuff.this, "Selected", Toast.LENGTH_SHORT).show(); + } else { + Toast.makeText(HelloFormStuff.this, "Not selected", Toast.LENGTH_SHORT).show(); } -}); +} </pre> -<p>This captures the {@link android.widget.CheckBox} element from the layout, then adds an {@link -android.view.View.OnClickListener}. The {@link android.view.View.OnClickListener} must implement the -{@link android.view.View.OnClickListener#onClick(View)} callback method, which -defines the action to be made when the checkbox is clicked. When clicked, {@link -android.widget.CompoundButton#isChecked()} is called to check the new state of the check box. If it -has been checked, then a {@link android.widget.Toast} displays the message "Selected", otherwise it -displays "Not selected". Note that the {@link android.view.View} object that is passed in the {@link -android.view.View.OnClickListener#onClick(View)} callback must be cast to a {@link -android.widget.CheckBox} because the {@link android.widget.CompoundButton#isChecked()} method is -not defined by the parent {@link android.view.View} class. The {@link android.widget.CheckBox} + +<p>When you specify this kind of method, which is used in your layout file with the {@code +android:onClick} +attribute, the method must be <code>public</code>, have a <code>void</code> return value, and +accept a single {@code android.view.View} parameter. When the system calls this method, it +passes the {@code android.view.View} that was clicked. In this example, the {@code +android.view.View} is cast to a {@link android.widget.CheckBox} to determine whether the widget +has been checked or unchecked. The {@link android.widget.CheckBox} widget handles its own state changes, so you only need to query the current state.</p> </li> <li>Run it.</li> @@ -240,44 +238,44 @@ android.widget.LinearLayout}): <RadioButton android:id="@+id/radio_red" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="Red" /> + android:text="Red" + android:onClick="onRadioButtonClicked"/> <RadioButton android:id="@+id/radio_blue" android:layout_width="wrap_content" android:layout_height="wrap_content" - android:text="Blue" /> + android:text="Blue" + android:onClick="onRadioButtonClicked"/> </RadioGroup> </pre> <p>It's important that the {@link android.widget.RadioButton}s are grouped together by the {@link android.widget.RadioGroup} element so that no more than one can be selected at a time. This logic is automatically handled by the Android system. When one {@link android.widget.RadioButton} within a group is selected, all others are automatically deselected.</p> + <p>The attribute <code>android:onClick</code> specifies the name of a method in your activity +that the system should call when the user clicks the radio button. You'll create that method +next.</p> </li> -<li>To do something when each {@link android.widget.RadioButton} is selected, you need an -{@link android.view.View.OnClickListener}. In this case, you want the listener to be re-usable, so -add the following code to create a new member in the <code>HelloFormStuff</code> Activity: -<pre> -private OnClickListener radio_listener = new OnClickListener() { - public void onClick(View v) { - // Perform action on clicks - RadioButton rb = (RadioButton) v; - Toast.makeText(HelloFormStuff.this, rb.getText(), Toast.LENGTH_SHORT).show(); - } -}; -</pre> -<p>First, the {@link android.view.View} that is passed to the {@link -android.view.View.OnClickListener#onClick(View)} method is cast into a RadioButton. Then a -{@link android.widget.Toast} message displays the selected radio button's text.</p> -<li>Now, at the bottom of the {@link android.app.Activity#onCreate(Bundle) onCreate()} method, add -the following: +<li>To do something when each {@link android.widget.RadioButton} is selected, add the following +method inside your {@link android.app.Activity} class:</p> + <pre> - final RadioButton radio_red = (RadioButton) findViewById(R.id.radio_red); - final RadioButton radio_blue = (RadioButton) findViewById(R.id.radio_blue); - radio_red.setOnClickListener(radio_listener); - radio_blue.setOnClickListener(radio_listener); +public void onRadioButtonClicked(View v) { + // Perform action on clicks + RadioButton rb = (RadioButton) v; + Toast.makeText(HelloFormStuff.this, rb.getText(), Toast.LENGTH_SHORT).show(); +} </pre> -<p>This captures each of the {@link android.widget.RadioButton}s from the layout and adds the -newly-created {@link android.view.View.OnClickListener} to each.</p> + +<p>When you specify this kind of method, which is used in your layout file with the {@code +android:onClick} +attribute, the method must be <code>public</code>, have a <code>void</code> return value, and +accept a single {@code android.view.View} parameter. When the system calls this method, it +passes the {@code android.view.View} that was clicked.</p> +<p>Because each {@link android.widget.RadioButton} widget is grouped into a {@link +android.widget.RadioGroup}, each widget handles its own state changes when a new button is +selected.</p> +</li> <li>Run the application.</li> </ol> @@ -303,31 +301,35 @@ element (inside the {@link android.widget.LinearLayout}): android:layout_width="wrap_content" android:layout_height="wrap_content" android:textOn="Vibrate on" - android:textOff="Vibrate off"/> + android:textOff="Vibrate off" + android:onClick="onToggleClicked"/> </pre> <p>The attributes <code>android:textOn</code> and <code>android:textOff</code> specify the text for the button when the button has been toggled on or off. The default values are "ON" and "OFF".</p> + <p>The attribute <code>android:onClick</code> specifies the name of a method in your activity +that the system should call when the user clicks the button. You'll create that method next.</p> </li> -<li>To do something when the state is changed, add the following code -to the end of the {@link android.app.Activity#onCreate(Bundle) onCreate()} method: +<li>To do something when the user clicks the button, add the following +method inside your {@link android.app.Activity} class:</p> + <pre> -final ToggleButton togglebutton = (ToggleButton) findViewById(R.id.togglebutton); -togglebutton.setOnClickListener(new OnClickListener() { - public void onClick(View v) { - // Perform action on clicks - if (togglebutton.isChecked()) { - Toast.makeText(HelloFormStuff.this, "Checked", Toast.LENGTH_SHORT).show(); - } else { - Toast.makeText(HelloFormStuff.this, "Not checked", Toast.LENGTH_SHORT).show(); - } +public void onToggleClicked(View v) { + // Perform action on clicks + if (((ToggleButton) v).isChecked()) { + Toast.makeText(HelloFormStuff.this, "Toggle on", Toast.LENGTH_SHORT).show(); + } else { + Toast.makeText(HelloFormStuff.this, "Toggle off", Toast.LENGTH_SHORT).show(); } -}); +} </pre> -<p>This captures the {@link android.widget.ToggleButton} element from the layout, then adds an -{@link android.view.View.OnClickListener}. The {@link android.view.View.OnClickListener} must -implement the {@link android.view.View.OnClickListener#onClick(View)} callback method, which -defines the action to perform when the button is clicked. In this example, the callback + +<p>When you specify this kind of method, which is used in your layout file with the {@code +android:onClick} +attribute, the method must be <code>public</code>, have a <code>void</code> return value, and +accept a single {@code android.view.View} parameter. When the system calls this method, it +passes the {@code android.view.View} that was clicked.</p> +<p>In this example, the callback method checks the new state of the button, then shows a {@link android.widget.Toast} message that indicates the current state.</p> diff --git a/docs/html/resources/tutorials/views/hello-mapview.jd b/docs/html/resources/tutorials/views/hello-mapview.jd index ac5e826..7a0bedf 100644 --- a/docs/html/resources/tutorials/views/hello-mapview.jd +++ b/docs/html/resources/tutorials/views/hello-mapview.jd @@ -208,7 +208,7 @@ public int size() { new class constructor: <pre> public HelloItemizedOverlay(Drawable defaultMarker, Context context) { - super(defaultMarker); + super(boundCenterBottom(defaultMarker)); mContext = context; } </pre> diff --git a/docs/html/resources/tutorials/views/hello-webview.jd b/docs/html/resources/tutorials/views/hello-webview.jd index 2d07647..f6a6a71 100644 --- a/docs/html/resources/tutorials/views/hello-webview.jd +++ b/docs/html/resources/tutorials/views/hello-webview.jd @@ -52,7 +52,7 @@ public void onCreate(Bundle savedInstanceState) { <li>While you're in the manifest, give some more space for web pages by removing the title bar, with the "NoTitleBar" theme: <pre> -<activity android:name=".HelloGoogleMaps" android:label="@string/app_name" +<activity android:name=".HelloWebView" android:label="@string/app_name" <strong>android:theme="@android:style/Theme.NoTitleBar"</strong>> </pre> </li> diff --git a/docs/html/sdk/adding-components.jd b/docs/html/sdk/adding-components.jd index ca27bba..599b2a8 100644 --- a/docs/html/sdk/adding-components.jd +++ b/docs/html/sdk/adding-components.jd @@ -1,4 +1,4 @@ -page.title=Adding SDK Components +page.title=Adding SDK Packages @jd:body @@ -6,74 +6,74 @@ page.title=Adding SDK Components <div id="qv"> <h2>Quickview</h2> <ul> - <li>Use the Android SDK and AVD Manager to + <li>Use the Android SDK Manager to set up your SDK and keep it up-to-date.</li> </ul> <h2>In this document</h2> <ol> - <li><a href="#launching">Launching the Android SDK and AVD Manager</a> - <li><a href="#InstallingComponents">Installing SDK Components</a> - <li><a href="#UpdatingComponents">Updating SDK Components</a> - <li><a href="#dependencies">Component Dependencies</a></li> + <li><a href="#launching">Launching the Android SDK Manager</a> + <li><a href="#InstallingComponents">Installing SDK Packages</a> + <li><a href="#UpdatingComponents">Updating SDK Packages</a> + <li><a href="#dependencies">Package Dependencies</a></li> <li><a href="#AddingSites">Adding New Sites</a></li> <li><a href="#troubleshooting">Troubleshooting</a></li> </ol> </div> </div> -<p>Adding and updating components in your Android SDK is fast and easy. To add or -update the individual SDK components that you need, use the <em>Android SDK and AVD +<p>Adding and updating packages in your Android SDK is fast and easy. To add or +update the individual SDK packages that you need, use the <em>Android SDK Manager</em> (included in the SDK Tools).</p> <p>It only takes a couple of clicks to install individual versions of the Android platform, new development tools, new documentation, and SDK add-ons. The -new SDK components are automatically installed into your existing SDK directory, +new SDK packages are automatically installed into your existing SDK directory, so you don't need to update your development environment to specify a new SDK location.</p> <p>If you're setting up your Android SDK for the first time, see <a href="{@docRoot}sdk/installing.html#components">Installing the SDK</a> for information about -what components to install.</p> +what packages to install.</p> <p class="note"><strong>Note:</strong> If you develop in Eclipse, you might also need to update your ADT plugin when you update your development tools. See the revisions listed in the <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a> document.</p> <img src="{@docRoot}images/sdk_manager_packages.png" alt="" /> -<p class="img-caption"><strong>Figure 1.</strong> The Android SDK and AVD Manager's -<strong>Available Packages</strong> panel, which shows the SDK components that are +<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager's +<strong>Available Packages</strong> panel, which shows the SDK packages that are available for you to download into your environment. </p> </div> -<h2 id="launching">Launching the Android SDK and AVD Manager</h2> +<h2 id="launching">Launching the Android SDK Manager</h2> -<p>The Android SDK and AVD Manager is the tool that you use to install and -upgrade SDK components in your development environment. </p> +<p>The Android SDK Manager is the tool that you use to install and +upgrade SDK packages in your development environment. </p> -<p>You can launch the Android SDK and AVD Manager in one of the following ways.</p> +<p>You can launch the Android SDK Manager in one of the following ways.</p> <h4>Launching from Eclipse/ADT</h4> <p>If you are developing in Eclipse and have already installed the ADT Plugin, -follow these steps to access the Android SDK and AVD Manager tool:</p> +follow these steps to access the Android SDK Manager tool:</p> <ol> <li>Open Eclipse</li> -<li>Select <strong>Window</strong> > <strong>Android SDK and AVD +<li>Select <strong>Window</strong> > <strong>Android SDK Manager</strong>.</li> </ol> <h4>Launching from the SDK Manager script (Windows only)</h4> -<p>For Windows only, the SDK includes a script that invokes the Android SDK and -AVD Manager. To launch the tool using the script, double-click {@code SDK +<p>For Windows only, the SDK includes a script that invokes the Android SDK Manager. To launch the +tool using the script, double-click {@code SDK Manager.exe} at the root of the the SDK directory.</p> <h4>Launching from a command line</h4> -<p>In all development environments, follow these steps to access the Android SDK -and AVD Manager tool from the command line: </p> +<p>In all development environments, follow these steps to access the Android SDK Manager tool from +the command line: </p> <ol> <li>Navigate to the <code><<em>sdk</em>>/tools/</code> directory.</li> @@ -82,26 +82,26 @@ and AVD Manager tool from the command line: </p> </ol> -<h2 id="InstallingComponents">Installing SDK Components</h2> +<h2 id="InstallingComponents">Installing SDK Packages</h2> -<p class="caution"><strong>Caution:</strong> Before you install SDK components, +<p class="caution"><strong>Caution:</strong> Before you install SDK packages, we recommend that you disable any antivirus software that may be running on your computer. There are cases in which antivirus software on Windows is known to interfere with the installation process, so we suggest you disable your antivirus until installation is complete.</p> -<p>Follow these steps to install new SDK components in your environment:</p> +<p>Follow these steps to install new SDK packages in your environment:</p> <ol> - <li>Launch the Android SDK and AVD Manager as described in the section above.</li> + <li>Launch the Android SDK Manager as described in the section above.</li> <li>Select <strong>Available Packages</strong> in the left panel. - This will reveal all of the components that are currently available for download + This will reveal all of the packages that are currently available for download from the SDK repository.</li> - <li>Select the component(s) you'd like to install and click <strong>Install + <li>Select the package(s) you'd like to install and click <strong>Install Selected</strong>. (If you aren't sure which packages to select, read <a - href="installing.html#which">Recommended Components</a>.)</li> - <li>Verify and accept the components you want (ensure each one is selected with a green -checkmark) and click <strong>Install</strong>. The components will now be installed into + href="installing.html#which">Recommended Packages</a>.)</li> + <li>Verify and accept the packages you want (ensure each one is selected with a green +checkmark) and click <strong>Install</strong>. The packages will now be installed into your existing Android SDK directories.</li> </ol> @@ -114,60 +114,60 @@ and new documentation is saved in the existing <code><sdk>/docs/</code> directory (old docs are replaced).</p> -<h2 id="UpdatingComponents">Updating SDK Components</h2> +<h2 id="UpdatingComponents">Updating SDK Packages</h2> -<p>From time to time, new revisions of existing SDK components are released and +<p>From time to time, new revisions of existing SDK packages are released and made available to you through the SDK repository. In most cases, if you have those -components installed in your environment, you will want +packages installed in your environment, you will want to download the new revisions as soon as possible. </p> <p>You can learn about the release of new revisions in two ways: </p> <ul> <li>You can watch for updates listed in the "SDK" tab of the Android Developers -site, in the "Downloadable SDK Components" section. </li> +site, in the "Downloadable SDK Packages" section. </li> <li>You can watch for updates listed in the <strong>Available Packages</strong> -panel of the Android SDK and AVD Manager. </li> +panel of the Android SDK Manager. </li> </ul> -<p>When you see that a new revision is available, you can use the Android SDK -and AVD Manager to quickly download it to your environment. Follow the same -procedure as given in <a href="#InstallingComponents">Installing SDK Components</a>, above. The new -component is installed in place of the old, but without impacting your +<p>When you see that a new revision is available, you can use the Android SDK Manager to quickly +download it to your environment. Follow the same +procedure as given in <a href="#InstallingComponents">Installing SDK Packages</a>, above. The new +package is installed in place of the old, but without impacting your applications. </p> <p class="note"><strong>Tip:</strong> -Use the "Display updates only" checkbox to show only the components +Use the "Display updates only" checkbox to show only the packages you do not have.</p> -<h2 id="dependencies">SDK Component Dependencies</h2> +<h2 id="dependencies">SDK Package Dependencies</h2> -<p>In some cases, an SDK component may require a specific minimum revision of -another component or SDK tool. Where such dependencies exist, they are -documented in the revision notes for each component, available from the links in -the "Downloadable SDK Components" section at left.</p> +<p>In some cases, an SDK package may require a specific minimum revision of +another package or SDK tool. Where such dependencies exist, they are +documented in the revision notes for each package, available from the links in +the "Downloadable SDK packages" section at left.</p> <p>For example, there may be a dependency between the ADT Plugin for Eclipse and -the SDK Tools component. When you install the SDK Tools -component, you should also upgrade to the required version of ADT (if you +the SDK Tools package. When you install the SDK Tools +package, you should also upgrade to the required version of ADT (if you are developing in Eclipse). In this case, the major version number for your ADT plugin should always match the revision number of your SDK Tools (for example, ADT 8.x requires SDK Tools r8). </p> <p>Also make sure that, each time you install a new version of the Android platform, you have -the latest version of the SDK Platform-tools component. The SDK Platform-tools contain +the latest version of the SDK Platform-tools package. The SDK Platform-tools contain tools that are backward compatible with all versions of the Android platform and are often updated to support new features in the latest version of the Android platform.</p> <p>The development tools will notify you with debug warnings if there is dependency that you need to -address. The SDK and AVD Manager also enforces dependencies by requiring that you download any -components that are needed by those you have selected.</p> +address. The Android SDK Manager also enforces dependencies by requiring that you download any +packages that are needed by those you have selected.</p> <h2 id="AddingSites">Adding New Sites</h2> -<p>By default, <strong>Available Packages</strong> displays components available from the +<p>By default, <strong>Available Packages</strong> displays packages available from the <em>Android Repository</em> and <em>Third party Add-ons</em>. You can add other sites that host their own Android SDK add-ons, then download the SDK add-ons from those sites.</p> @@ -178,7 +178,7 @@ to develop using their libraries, you must install their Android SDK add-on, if available under <em>Third party Add-ons</em>. </p> <p>If a carrier or device manufacturer has hosted an SDK add-on repository file -on their web site, follow these steps to add their site to the SDK and AVD +on their web site, follow these steps to add their site to the Android SDK Manager:</p> <ol> @@ -186,7 +186,7 @@ Manager:</p> <li>Click <strong>Add Add-on Site</strong> and enter the URL of the {@code repository.xml} file. Click <strong>OK</strong>.</li> </ol> -<p>Any SDK components available from the site will now be listed under a new item named +<p>Any SDK packages available from the site will now be listed under a new item named <strong>User Add-ons</strong>.</p> @@ -194,12 +194,12 @@ Manager:</p> <p><strong>Problems connecting to the SDK repository</strong></p> -<p>If you are using the SDK and AVD Manager to download components and are encountering +<p>If you are using the Android SDK Manager to download packages and are encountering connection problems, try connecting over http, rather than https. To switch the -protocol used by the SDK and AVD Manager, follow these steps: </p> +protocol used by the Android SDK Manager, follow these steps: </p> <ol> - <li>With the Android SDK and AVD Manager window open, select "Settings" in the + <li>With the Android SDK Manager window open, select "Settings" in the left pane. </li> <li>On the right, in the "Misc" section, check the checkbox labeled "Force https://... sources to be fetched using http://..." </li> diff --git a/docs/html/sdk/android-1.6-highlights.jd b/docs/html/sdk/android-1.6-highlights.jd index 84766d6..f0a50fb 100644 --- a/docs/html/sdk/android-1.6-highlights.jd +++ b/docs/html/sdk/android-1.6-highlights.jd @@ -38,7 +38,7 @@ This page provides an overview of some new features and technologies.</p> <ul> <li><a href="#UserFeatures">New User Features</a></li> - <li><a href="#AndroidMarketUpdates">Android Market Updates</a></li> + <li><a href="#GooglePlayUpdates">Google Play Updates</a></li> <li><a href="#PlatformTechnologies">New Platform Technologies</a></li> </ul> @@ -118,14 +118,14 @@ on the new accessibility framework and enable them in Settings.</p> -<h2 id="AndroidMarketUpdates" style="clear:right">Android Market Updates</h2> +<h2 id="GooglePlayUpdates" style="clear:right">Google Play Updates</h2> <div class="screenshot" style="margin-top:-35px"> <img src="images/market.png" class="screenshot" alt="" /><br/> -New Android Market UI +New Google Play UI </div> -<p>For devices with Android Market, the latest version improves the overall user experience and makes +<p>For devices with Google Play, the latest version improves the overall user experience and makes it easier for users to discover great apps and games from developers.</p> <ul> @@ -157,7 +157,7 @@ they'd like to receive suggestions, under Searchable items in the Search setting It allows any Android application to "speak" a string of text with an accent that matches the language. The engine supports the following languages: English (American and British accents), French, Italian, German and Spanish. If you're using a T-Mobile G1 or Dream device, you'll need to download the -SpeechSynthesis Data Installer from Android Market, which includes the "voices" needed by the +SpeechSynthesis Data Installer from Google Play, which includes the "voices" needed by the text-to-speech engine.</p> diff --git a/docs/html/sdk/android-2.1.jd b/docs/html/sdk/android-2.1.jd index 3f28551..1ee833c 100644 --- a/docs/html/sdk/android-2.1.jd +++ b/docs/html/sdk/android-2.1.jd @@ -191,7 +191,7 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html"><code><uses- <uses-feature android:name="android.software.live_wallpaper" /> </pre> -<p>When you've published your application, Android Market checks for the +<p>When you've published your application, Google Play checks for the presence of this element and uses it as a filter, ensuring that your application is not made available to users whose devices do not support Live Wallpapers. </p> diff --git a/docs/html/sdk/android-2.2-highlights.jd b/docs/html/sdk/android-2.2-highlights.jd index 8bed675..37a20d5 100644 --- a/docs/html/sdk/android-2.2-highlights.jd +++ b/docs/html/sdk/android-2.2-highlights.jd @@ -231,7 +231,7 @@ two-way push sync functionality.</p> <h3>Android Application Error Reports</h3> -<p>New bug reporting feature for Android Market apps enables developers to receive crash and freeze +<p>New bug reporting feature for Google Play apps enables developers to receive crash and freeze reports from their users. The reports will be available when they log into their publisher account.</p> diff --git a/docs/html/sdk/android-2.3.3.jd b/docs/html/sdk/android-2.3.3.jd index 023e2e4..405c063 100644 --- a/docs/html/sdk/android-2.3.3.jd +++ b/docs/html/sdk/android-2.3.3.jd @@ -192,7 +192,7 @@ underlying hardware support.</p> declaring <code><uses-permission android:name="android.permission.NFC"></code> in their manifest files.</p> -<p>Additionally, developers can request filtering on Android Market, such that +<p>Additionally, developers can request filtering on Google Play, such that their applications are not discoverable to users whose devices do not support NFC. To request filtering, add <code><uses-feature android:name="android.hardware.nfc" diff --git a/docs/html/sdk/android-2.3.4.jd b/docs/html/sdk/android-2.3.4.jd index eeaa69a..4bfdabd 100644 --- a/docs/html/sdk/android-2.3.4.jd +++ b/docs/html/sdk/android-2.3.4.jd @@ -197,7 +197,7 @@ accessories support, for runtime testing against connected devices</li> accessories, please see the related <a href="{@docRoot}guide/topics/usb/index.html">developer documentation</a>.</p> -<p>Additionally, developers can request filtering on Android Market, such that +<p>Additionally, developers can request filtering on Google Play, such that their applications are not available to users whose devices do not provide the appropriate accessory support. To request filtering, add the element below to the application manifest:</p> diff --git a/docs/html/sdk/android-2.3.jd b/docs/html/sdk/android-2.3.jd index fc4f5aa..b466913 100644 --- a/docs/html/sdk/android-2.3.jd +++ b/docs/html/sdk/android-2.3.jd @@ -150,7 +150,7 @@ declaring <code><uses-permission android:name="android.permission.INTERNET"></code> and <code><uses-permission android:name="android.permission.USE_SIP"></code> in their manifest files.</p> -<p>Additionally, developers can request filtering on Android Market, such that +<p>Additionally, developers can request filtering on Google Play, such that their applications are not discoverable to users whose devices do not include the platform’s SIP stack and services. To request filtering, add <code><uses-feature android:name="android.software.sip" @@ -197,7 +197,7 @@ however, regardless of underlying hardware support.</p> declaring <code><uses-permission android:name="android.permission.NFC"></code> in their manifest files.</p> -<p>Additionally, developers can request filtering on Android Market, such that +<p>Additionally, developers can request filtering on Google Play, such that their applications are not discoverable to users whose devices do not support NFC. To request filtering, add <code><uses-feature android:name="android.hardware.nfc" @@ -219,7 +219,7 @@ code. </p> <p>Note that the specific set of hardware sensors available on any given device varies at the discretion of the device manufacturer. </p> -<p>Developers can request filtering in Android Market, such that their +<p>Developers can request filtering on Google Play, such that their applications are not discoverable to users whose devices do not offer a gyroscope sensor. To do so, add <code><uses-feature android:name="android.hardware.sensor.gyroscope" @@ -726,7 +726,7 @@ the {@link android.net.sip SIP API} to make or receive internet calls. <p>The platform adds several new hardware features that developers can declare in their application manifests as being required by their applications. This lets developers control how their application is filtered, when published on -Android Market. </p> +Google Play. </p> <ul> <li>{@link android.content.pm.PackageManager#FEATURE_AUDIO_LOW_LATENCY diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd index 49fefee..3acb358 100644 --- a/docs/html/sdk/android-3.0.jd +++ b/docs/html/sdk/android-3.0.jd @@ -25,7 +25,8 @@ Differences Report »</a> </li> <h2>See Also</h2> <ol> - <li><a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li> + <li><a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and +Handsets</a></li> </ol> </div> @@ -41,7 +42,7 @@ libraries.</p> <p>To get started developing or testing against Android {@sdkPlatformVersion}, use the Android SDK Manager to download the platform into your SDK. For more information, see <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>. If you are new to Android, <a +href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>. If you are new to Android, <a href="{@docRoot}sdk/index.html">download the SDK Starter Package</a> first.</p> <p>For a high-level introduction to Android {@sdkPlatformVersion}, see the <a @@ -52,8 +53,8 @@ Highlights</a>.</p> If you've already published an Android application, please test and optimize your application on Android 3.0 as soon as possible. You should do so to be sure your application provides the best experience possible on the latest Android-powered devices. For information about what you can do, -read <a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android -3.0</a>.</p> +read <a href="{@docRoot}guide/practices/tablets-and-handsets.html">Supporting Tablets and +Handsets</a>.</p> <h2 id="relnotes">Revisions</h2> @@ -922,7 +923,7 @@ parse mode is also compatible with the {@link org.json}'s default parser.</p> <p>The <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> -manfest element should be used to inform external entities (such as Android Market) of the set of +manfest element should be used to inform external entities (such as Google Play) of the set of hardware and software features on which your application depends. In this release, Android adds the following new constants that applications can declare with this element:</p> diff --git a/docs/html/sdk/android-3.1.jd b/docs/html/sdk/android-3.1.jd index b9cf969..7ec7e33 100644 --- a/docs/html/sdk/android-3.1.jd +++ b/docs/html/sdk/android-3.1.jd @@ -214,7 +214,7 @@ for USB host and open accessory modes on specific devices is determined by their manufacturers. In particular, host mode relies on appropriate USB controller hardware in the Android-powered device. </p> -<p>Additionally, developers can request filtering on Android Market, such that +<p>Additionally, developers can request filtering on Google Play, such that their applications are not availabe to users whose devices do not provide the appropriate USB support. To request filtering, add one or both of the elements below to the application manifest, as appropriate: </p> @@ -908,8 +908,8 @@ desktop).</li> <h3 id="features">New feature constants</h3> <p>The platform adds new hardware feature constants that developers can declare -in their application manifests, to inform external entities such as Android -Market of the application's requirement for new hardware capabilities supported +in their application manifests, to inform external entities such as Google +Play of the application's requirement for new hardware capabilities supported in this version of the platform. Developers declare these and other feature constants in <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code @@ -926,11 +926,11 @@ to communicate with external hardware devices connected over USB and function as devices.</li> </ul> -<p>Android Market filters applications based on features declared in <a +<p>Google Play filters applications based on features declared in <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> manifest elements. For more information about declaring features in an application manifest, read <a -href="{@docRoot}guide/appendix/market-filters.html">Android Market +href="{@docRoot}guide/appendix/market-filters.html">Google Play Filters</a>.</p> diff --git a/docs/html/sdk/android-3.2.jd b/docs/html/sdk/android-3.2.jd index aeaf9c8..27df22c 100644 --- a/docs/html/sdk/android-3.2.jd +++ b/docs/html/sdk/android-3.2.jd @@ -320,7 +320,7 @@ considers the application incompatible with the device, but does not prevent it from being installed and run.</li> </ul> -<p class="note"><strong>Note:</strong> Android Market does not currently filter +<p class="note"><strong>Note:</strong> Google Play does not currently filter apps based on any of the attributes above. Support for filtering will be added in a later platform release. Applications that require filtering based on screen size can use the existing <code><supports-screens></code> @@ -526,13 +526,13 @@ automatically by the platform.</p> <h3 id="features">New feature constants</h3> <p>The platform adds new hardware feature constants that you can declare -in their application manifests, to inform external entities such as Android -Market of required hardware and software capabilities. You declare these +in their application manifests, to inform external entities such as Google +Play of required hardware and software capabilities. You declare these and other feature constants in <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> manifest elements. -<p>Android Market filters applications based on their <code><uses-feature></code> attributes, to ensure that they are available only to devices on which their requirements are met. </p> +<p>Google Play filters applications based on their <code><uses-feature></code> attributes, to ensure that they are available only to devices on which their requirements are met. </p> <ul> <li>Feature constants for landscape or portrait requirements diff --git a/docs/html/sdk/android-4.0-highlights.jd b/docs/html/sdk/android-4.0-highlights.jd index 922bb08..98f467d 100644 --- a/docs/html/sdk/android-4.0-highlights.jd +++ b/docs/html/sdk/android-4.0-highlights.jd @@ -343,7 +343,7 @@ capabilities</strong></p> <p>The Camera app includes many new features that let users capture special moments with great photos and videos. After capturing images, they can edit and share -them easily with friemds. </p> +them easily with friends. </p> <p>When taking pictures, <strong>continuous focus</strong>, <strong>zero shutter lag exposure</strong>, and decreased shot-to-shot speed help capture clear, @@ -529,7 +529,7 @@ use — there’s no menu to open, application to launch, or pairing needed. Just touch one Android-powered phone to another, then tap to send.</p> <p>For sharing apps, Android Beam pushes a link to the app's details page in -Android Market. On the other device, the Market app launches and loads the +Google Play. On the other device, the Google Play client app launches and loads the details page, for easy downloading of the app. Individual apps can build on Android Beam to add other types of interactions, such as passing game scores, initiating a multiplayer game or chat, and more.</p> @@ -715,7 +715,7 @@ data over Bluetooth, without the need for user-visible pairing.</p> <p>Even if developers do not add custom interactions based on Android Beam they can still benefit from it being deeply integrated into Android. By default the -system shares the app’s Android Market URL, so it’s easy for the user to +system shares the app’s Google Play URL, so it’s easy for the user to download or purchase the app right away.</p> diff --git a/docs/html/sdk/android-4.0.3.jd b/docs/html/sdk/android-4.0.3.jd index 809c83c..f6dbee0 100644 --- a/docs/html/sdk/android-4.0.3.jd +++ b/docs/html/sdk/android-4.0.3.jd @@ -68,15 +68,19 @@ the Android 4.0.x system components will not be available for download.</p> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" alt="" /> - Android {@sdkPlatformVersion}, Revision 2</a> <em>(January 2012)</em> + Revision 3</a> <em>(March 2012)</em> </a></p> <div class="toggle-content-toggleme" style="padding-left:2em;"> -<dl> -<dt>Maintenance release. SDK Tools r14 or higher is required. -</dt> -</dl> + <p>Maintenance update. The system version is 4.0.4.</p> + <p class="note"><strong>Note:</strong> This system image includes support for emulator +hardware graphics acceleration when used with SDK Tools r17 or higher. +(<a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">more info</a>)</p> + <dl> + <dt>Dependencies:</dt> + <dd>SDK Tools r17 or higher is required.</dd> + </dl> </div> </div> @@ -86,15 +90,35 @@ class="toggle-content-img" alt="" /> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img" alt="" /> - Android {@sdkPlatformVersion}, Revision 1</a> <em>(December 2011)</em> + Revision 2</a> <em>(January 2012)</em> </a></p> <div class="toggle-content-toggleme" style="padding-left:2em;"> -<dl> -<dt>Initial release. SDK Tools r14 or higher is required. -</dt> -</dl> + <p>Maintenance update. The system version is 4.0.3.</p> + <dl> + <dt>Dependencies:</dt> + <dd>SDK Tools r14 or higher is required.</dd> + </dl> + + </div> +</div> + +<div class="toggle-content closed" style="padding-left:1em;"> + + <p><a href="#" onclick="return toggleContent(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" +class="toggle-content-img" alt="" /> + Revision 1</a> <em>(December 2011)</em> + </a></p> + + <div class="toggle-content-toggleme" style="padding-left:2em;"> + + <p>Initial release. The system version is 4.0.3.</p> + <dl> + <dt>Dependencies:</dt> + <dd>SDK Tools r14 or higher is required.</dd> + </dl> </div> </div> diff --git a/docs/html/sdk/android-4.0.jd b/docs/html/sdk/android-4.0.jd index 2cad86b..e3b13c8 100644 --- a/docs/html/sdk/android-4.0.jd +++ b/docs/html/sdk/android-4.0.jd @@ -660,14 +660,14 @@ your application’s package name. When the other device receives the NDEF messa application record and multiple applications contain activities that handle the specified intent, the system always delivers the message to the activity in your application (based on the matching application record). If the target device does not currently have your application installed, the -system uses the Android application record to launch Android Market and take the user to the +system uses the Android application record to launch Google Play and take the user to the application in order to install it.</p> <p>If your application doesn’t use NFC APIs to perform NDEF Push messaging, then Android provides a default behavior: When your application is in the foreground on one device and Android Beam is invoked with another Android-powered device, then the other device receives an NDEF message with an Android application record that identifies your application. If the receiving device has the -application installed, the system launches it; if it’s not installed, Android Market opens and takes +application installed, the system launches it; if it’s not installed, Google Play opens and takes the user to your application in order to install it.</p> <p>You can read more about Android Beam and other NFC features in the <a diff --git a/docs/html/sdk/compatibility-library.jd b/docs/html/sdk/compatibility-library.jd index df71552..f81e8ae 100644 --- a/docs/html/sdk/compatibility-library.jd +++ b/docs/html/sdk/compatibility-library.jd @@ -46,11 +46,40 @@ by the directory name, such as {@code v4/} and {@code v13/}.</p> <p>The sections below provide notes about successive releases of the Support Package, as denoted by revision number.</p> - <div class="toggle-content open"> <p><a href="#" onclick="return toggleContent(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img" /> + Support Package, revision 7 (March 2012) + </a></p> + + <div class="toggle-content-toggleme" style="padding-left:2em"> + <dl> + <dt>Changes for v4 support library:</dt> + <dd> + <ul> + <li>Added {@link android.support.v4.app.ShareCompat}, which provides helper classes +for sending and receiving content for social sharing applications, including new metadata for +attributing shared data to the source app. This class also provides compatible integration with the +new {@link android.widget.ShareActionProvider} in Android 4.0.</li> + <li>Added {@link android.support.v4.app.NavUtils} and {@link +android.support.v4.app.TaskStackBuilder} to provide support for implementing the +<a href="{@docRoot}design/index.html">Android Design</a> guidelines for navigation. These +additions include a way to implement the action bar's <em>Up</em> button across versions. +For an example implementation of this pattern, see the AppNavigation sample in +({@code <em><sdk></em>/samples/<em><platform></em>/AppNavigation}).</li> + <li>Added {@link android.support.v4.app.NotificationCompat.Builder} to provide a +compatibility implementation of Android 3.0's {@link android.app.Notification.Builder} helper class +for creating standardized system notifications.</li> + </ul> + </dd> + </dl> + </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" /> Support Package, revision 6 (December 2011) </a></p> @@ -301,13 +330,13 @@ Android 3.2 and higher (all other APIs in the v4 library are already available w <h2 id="Downloading">Downloading the Support Package</h2> -<p>The Support Package is provided as a downloadable package from the Android SDK and AVD +<p>The Support Package is provided as a downloadable package from the Android SDK Manager. To install:</p> <ol> - <li>Launch the SDK and AVD Manager. + <li>Launch the Android SDK Manager. <p>From Eclipse, you can select <strong>Window</strong> -> <strong>Android SDK and AVD Manager</strong>. Or, launch {@code SDK Manager.exe} from +> <strong>Android SDK Manager</strong>. Or, launch {@code SDK Manager.exe} from the {@code <sdk>/} directory (on Windows only) or {@code android} from the {@code <sdk>/tools/} directory.</p></li> <li>Expand the Android Repository, check <strong>Android Support package</strong> diff --git a/docs/html/sdk/eclipse-adt.jd b/docs/html/sdk/eclipse-adt.jd index 30825ee..e117118 100644 --- a/docs/html/sdk/eclipse-adt.jd +++ b/docs/html/sdk/eclipse-adt.jd @@ -1,8 +1,8 @@ page.title=ADT Plugin for Eclipse -adt.zip.version=16.0.1 -adt.zip.download=ADT-16.0.1.zip -adt.zip.bytes=7000078 -adt.zip.checksum=03a2a23650ddac128c8b9e8aaf0aa433 +adt.zip.version=18.0.0 +adt.zip.download=ADT-18.0.0.zip +adt.zip.bytes=12834793 +adt.zip.checksum=b446fa157ed97af79d1e21629201efbb @jd:body @@ -36,7 +36,7 @@ that is designed to give you a powerful, integrated environment in which to build Android applications.</p> <p>ADT extends the capabilities of Eclipse to let you quickly set up new Android -projects, create an application UI, add components based on the Android +projects, create an application UI, add packages based on the Android Framework API, debug your applications using the Android SDK tools, and even export signed (or unsigned) {@code .apk} files in order to distribute your application.</p> @@ -113,6 +113,141 @@ padding: .25em 1em; <a href="#" onclick="return toggleDiv(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-img" height="9px" width="9px" /> +ADT 18.0.0</a> <em>(April 2012)</em> + <div class="toggleme"> +<dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Java 1.6 or higher is required for ADT 18.0.0.</li> + <li>Eclipse Helios (Version 3.6.2) or higher is required for ADT 18.0.0.</li> + <li>ADT 18.0.0 is designed for use with <a href="{@docRoot}sdk/tools-notes.html">SDK Tools + r18</a>. If you haven't already installed SDK Tools r18 into your SDK, use the Android SDK + Manager to do so.</li> + </ul> + </dd> + + <dt>Bug fixes:</dt> + <dd> + <ul> + <li>Fixed problem where exporting release package does not recompile libraries in release + mode. + (<a href="http://code.google.com/p/android/issues/detail?id=27940">Issue 27940</a>)</li> + </ul> + </dd> + +</dl> + +</div> +</div> + + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" +width="9px" /> +ADT 17.0.0</a> <em>(March 2012)</em> + <div class="toggleme"> +<dl> + <dt>Dependencies:</dt> + + <dd> + <ul> + <li>Java 1.6 or higher is required for ADT 17.0.0.</li> + <li>Eclipse Helios (Version 3.6.2) or higher is required for ADT 17.0.0.</li> + <li>ADT 17.0.0 is designed for use with <a href="{@docRoot}sdk/tools-notes.html">SDK Tools + r17</a>. If you haven't already installed SDK Tools r17 into your SDK, use the Android SDK + Manager to do so.</li> + </ul> + </dd> + + <dt>General improvements:</dt> + <dd> + <ul> + <li>New build features + <ul> + <li>Added feature to automatically setup JAR dependencies. Any {@code .jar} files in the + {@code /libs} folder are added to the build configuration (similar to how the Ant build + system works). Also, {@code .jar} files needed by library projects are also automatically + added to projects that depend on those library projects. + (<a href="http://tools.android.com/recent/dealingwithdependenciesinandroidprojects">more + info</a>)</li> + <li>Added a feature that allows you to run some code only in debug mode. Builds now +generate a class called {@code BuildConfig} containing a {@code DEBUG} constant that is +automatically set according to your build type. You can check the ({@code BuildConfig.DEBUG}) +constant in your code to run debug-only functions.</li> + <li>Added support for custom views with custom attributes in libraries. Layouts using +custom attributes must use the namespace URI {@code http://schemas.android.com/apk/res-auto} instead +of the URI that includes the app package name. This URI is replaced with the app specific one at +build time.</li> + </ul> + </li> + <li>Improved Lint features. See the <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r17</a> +release notes.</li> + <li>Improved the Lint user interface + <ul> + <li>Added <strong>Run Lint</strong> toolbar action with a dropdown menu for selecting +specific (or all) projects, clearing results and other actions.</li> + <li>Updated the results window to be organized as a tree rather than a flat list. Each +issue type has a single top level item, which makes it easier to quickly scan through the reported +issues and narrow down to the issues you are most interested in.</li> + <li>Added many new toolbar actions to the results window, including expand/collapse, +ignore in file, ignore in project, ignore everywhere, show options, and configure columns.</li> + <li>Added new column options for the <strong>Lint Warnings</strong> tab, such as +category, priority, project, file and line. The column selection (as well as the column sizes) are +persisted. You can also click on columns to sort by those values.</li> + <li>Added Enable All and Disable All buttons to the Lint Options dialog, and a search +filter textbox to filter by issue id, summary and severity.</li> + </ul> + </li> + <li>Added Quick Outline for XML editors (Ctrl-O, Command-O). This feature shows the structure +of the current file including icons and ids, lets you filter and quickly jump to specific ids.</li> + <li>Updated the resource chooser to shows the resolved value for resources. For example, +when selecting {@code @string/hello} the chooser displays a resolved value such as "Hello World"). +The resource chooser also now allows you to edit the chosen value directly.</li> + <li>Updated Layout Editor so that it does not assign default ids to layouts, includes and +merge tags. This behavior tended to pollute the namespace with a lot of unused resources since +layouts are not usually manipulated via code, or referenced from XML. (The RelativeLayout editor +automatically assigns ids to views without ids when pointing to them.)</li> + <li>Added ability to export screenshots from the Layout Editor</li> + </ul> + </dd> + + <dt>Bug fixes:</dt> + <dd> + <ul> + <li>Fixed problem using Layout Editor with {@link android.widget.SlidingDrawer} which could + not be dragged into the layout on some platforms.</li> + <li>Fixed preview rendering for {@link android.widget.SlidingDrawer} and + {@link android.widget.TabHost}. + (<a href="http://code.google.com/p/android/issues/detail?id=23022">Issue 23022</a>).</li> + <li>Fixed issues that could prevent layout rendering due to unresolvable resources. + (<a href="http://code.google.com/p/android/issues/detail?id=21046">Issue 21046</a>, + <a href="http://code.google.com/p/android/issues/detail?id=21051">Issue 21051</a>)</li> + <li>Fixed a bug in resource chooser which made some types of framework resources impossible to +select. (<a href="http://code.google.com/p/android/issues/detail?id=20589">Issue 20589</a>)</li> + <li>Fixed a bug in the formatter where a certain whitespace pattern could result in a + non-space character getting deleted. + (<a href="http://code.google.com/p/android/issues/detail?id=23940">Issue 23940</a>)</li> + <li>Fixed a locale bug affecting Turkish locales in particular. + (<a href="http://code.google.com/p/android/issues/detail?id=23747">Issue 23747</a>)</li> + <li>Fixed issue where dex complains about duplicate classes in cases where a Library + Project depends on the same jar files or Java-only projects.</li> + <li>Fixed issue where test projects had to independently reference the library projects used + by an app project. Now referencing only the app project is enough.</li> + </ul> + </dd> + +</dl> + +</div> +</div> + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" +width="9px" /> ADT 16.0.1</a> <em>(December 2011)</em> <div class="toggleme"> <dl> @@ -182,11 +317,11 @@ ADT 15.0.1</a> <em>(November 2011)</em> <div class="toggleme"> <dl> <dt>Dependencies:</dt> - + <dd>ADT 15.0.1 is designed for use with <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r15</a>. If you haven't already installed SDK Tools r15 into your SDK, use the Android SDK Manager to do so.</dd> - + <dt>Bug fixes:</dt> <dd> <ul> @@ -368,7 +503,7 @@ ADT 12.0.0</a> <em>(July 2011)</em> <dd>ADT 12.0.0 is designed for use with <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r12</a>. If you haven't already installed SDK Tools r12 into your SDK, use -the Android SDK and AVD Manager to do so.</dd> +the Android SDK Manager to do so.</dd> <dt>Visual Layout Editor:</dt> <dd> @@ -420,7 +555,7 @@ ADT 11.0.0</a> <em>(June 2011)</em> <dt>Dependencies:</dt> <dd>ADT 11.0.0 is designed for use with SDK Tools r11. If you haven't -already installed SDK Tools r11 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r11 into your SDK, use the Android SDK Manager to do so.</dd> <dt>Visual Refactoring:</dt> @@ -556,7 +691,7 @@ ADT 10.0.1</a> <em>(March 2011)</em> <dt>Dependencies:</dt> <dd>ADT 10.0.1 is designed for use with SDK Tools r10. If you haven't -already installed SDK Tools r10 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r10 into your SDK, use the Android SDK Manager to do so.</dd> <dt>General notes:</dt> @@ -586,7 +721,7 @@ ADT 10.0.0</a> <em>(February 2011)</em> <dt>Dependencies:</dt> <dd>ADT 10.0.0 is designed for use with SDK Tools r10. If you haven't -already installed SDK Tools r10 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r10 into your SDK, use the Android SDK Manager to do so.</dd> <dt>General notes:</dt> @@ -636,7 +771,7 @@ ADT 9.0.0</a> <em>(January 2011)</em> <dt>Dependencies:</dt> <dd>ADT 9.0.0 is designed for use with SDK Tools r9. If you haven't -already installed SDK Tools r9 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r9 into your SDK, use the Android SDK Manager to do so.</dd> <dt>General notes:</dt> @@ -745,7 +880,7 @@ ADT 8.0.1</a> <em>(December 2010)</em> <dt>Dependencies:</dt> <p><p>ADT 8.0.1 is designed for use with SDK Tools r8. If you haven't -already installed SDK Tools r8 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r8 into your SDK, use the Android SDK Manager to do so.</p></dd> <dt>General notes:</dt> @@ -774,7 +909,7 @@ ADT 8.0.0</a> <em>(December 2010)</em> <dt>Dependencies:</dt> <p><p>ADT 8.0.0 is designed for use with SDK Tools r8. If you haven't -already installed SDK Tools r8 into your SDK, use the Android SDK and AVD Manager to do +already installed SDK Tools r8 into your SDK, use the Android SDK Manager to do so.</p></dd> <dt>General notes:</dt> @@ -920,8 +1055,8 @@ ADT 0.9.6</a> <em>(March 2010)</em> <dt>Dependencies:</dt> <dd><p>ADT 0.9.6 is designed for use with SDK Tools r5 and later. Before -updating to ADT 0.9.6, we highly recommend that you use the Android SDK and -AVD Manager to install SDK Tools r5 into your SDK.</p></dd> +updating to ADT 0.9.6, we highly recommend that you use the Android SDK Manager to install SDK +Tools r5 into your SDK.</p></dd> <dt>General Notes:</dt> <dd> @@ -938,8 +1073,8 @@ first time with the SDK Usage panel.</li> <dt>AVD/SDK Manager:</dt> <dd> <ul> -<li>Adds support for platform samples components.</li> -<li>Improves support for dependency between components.</li> +<li>Adds support for platform samples packages.</li> +<li>Improves support for dependency between packages.</li> <li>AVDs now sorted by API level.</li> <li>The AVD creation dialog now enforces a minimum SD card size of 9MB.</li> <li>Prevents deletion of running AVDs.</li> @@ -987,9 +1122,9 @@ ADT 0.9.5</a> <em>(December 2009)</em> <dt>Dependencies:</dt> <dd><p>ADT 0.9.5 requires features provided in SDK Tools r4 or higher. If you install -ADT 0.9.5, which is highly recommended, you should use the Android SDK and AVD +ADT 0.9.5, which is highly recommended, you should use the Android SDK Manager to download the latest SDK Tools into your SDK. For more information, -see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> +see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</p> </dd> <dt>General notes:</dt> @@ -1014,9 +1149,9 @@ ADT 0.9.4</a> <em>(October 2009)</em> <dt>Dependencies:</dt> <dd><p>ADT 0.9.4 requires features provided in SDK Tools r3 or higher. If you install -ADT 0.9.4, which is highly recommended, you should use the Android SDK and AVD +ADT 0.9.4, which is highly recommended, you should use the Android SDK Manager to download the latest SDK Tools into your SDK. For more information, -see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> +see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</p> </dd> <dt>Project Creation Wizard:</dt> @@ -1218,9 +1353,9 @@ to follow these steps again instead of the default update instructions.</p> <h4>Other install errors</h4> <p>Note that there are features of ADT that require some optional -Eclipse components (for example, WST). If you encounter an error when -installing ADT, your Eclipse installion might not include these components. -For information about how to quickly add the necessary components to your +Eclipse packages (for example, WST). If you encounter an error when +installing ADT, your Eclipse installion might not include these packages. +For information about how to quickly add the necessary packages to your Eclipse installation, see the troubleshooting topic <a href="{@docRoot}resources/faq/troubleshooting.html#installeclipsecomponents">ADT Installation Error: "requires plug-in org.eclipse.wst.sse.ui"</a>.</p> @@ -1245,9 +1380,9 @@ you should update to it as soon as convenient. </p> <p>In some cases, a new revision of ADT will have a dependency on a specific revision of the Android SDK Tools. If such dependencies exist, you will need to -update the SDK Tools component of the SDK after installing the new revision of -ADT. To update the SDK Tools component, use the Android SDK and AVD Manager, as -described in <a href="adding-components.html">Adding SDK Components</a>.</p> +update the SDK Tools package of the SDK after installing the new revision of +ADT. To update the SDK Tools package, use the Android SDK Manager, as +described in <a href="adding-components.html">Adding SDK Packages</a>.</p> <p>To learn about new features of each ADT revision and also any dependencies on the SDK Tools, see the listings in the <a href="#notes">Revisions</a> diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd index 5cf05e0..b56ccdb 100644 --- a/docs/html/sdk/index.jd +++ b/docs/html/sdk/index.jd @@ -2,21 +2,21 @@ page.title=Android SDK page.metaDescription=Download the official Android SDK to develop apps for Android-powered devices. sdk.redirect=0 -sdk.win_installer=installer_r16-windows.exe -sdk.win_installer_bytes=29561554 -sdk.win_installer_checksum=3521dda4904886b05980590f83cf3469 +sdk.win_installer=installer_r18-windows.exe +sdk.win_installer_bytes=37456234 +sdk.win_installer_checksum=48b1fe7b431afe6b9c8a992bf75dd898 -sdk.win_download=android-sdk_r16-windows.zip -sdk.win_bytes=29562413 -sdk.win_checksum=6b926d0c0a871f1a946e65259984701a +sdk.win_download=android-sdk_r18-windows.zip +sdk.win_bytes=37448775 +sdk.win_checksum=bfbfdf8b2d0fdecc2a621544d706fa98 -sdk.mac_download=android-sdk_r16-macosx.zip -sdk.mac_bytes=26158334 -sdk.mac_checksum=d1dc2b6f13eed5e3ce5cf26c4e4c47aa +sdk.mac_download=android-sdk_r18-macosx.zip +sdk.mac_bytes=33903758 +sdk.mac_checksum=8328e8a5531c9d6f6f1a0261cb97af36 -sdk.linux_download=android-sdk_r16-linux.tgz -sdk.linux_bytes=22048174 -sdk.linux_checksum=3ba457f731d51da3741c29c8830a4583 +sdk.linux_download=android-sdk_r18-linux.tgz +sdk.linux_bytes=29731463 +sdk.linux_checksum=6cd716d0e04624b865ffed3c25b3485c @jd:body @@ -28,7 +28,7 @@ sdk.linux_checksum=3ba457f731d51da3741c29c8830a4583 <li>Install the SDK starter package from the table above. (If you're on Windows, download the installer for help with the initial setup.)</li> <li>Install the ADT Plugin for Eclipse (if you'll be developing in Eclipse).</li> - <li>Add Android platforms and other components to your SDK.</li> + <li>Add Android platforms and other packages to your SDK.</li> <li>Explore the contents of the Android SDK (optional).</li> </ol> diff --git a/docs/html/sdk/installing.jd b/docs/html/sdk/installing.jd index 1dce483..7461eb0 100644 --- a/docs/html/sdk/installing.jd +++ b/docs/html/sdk/installing.jd @@ -53,10 +53,10 @@ function toggleDiv(link) { <li><a href="#Preparing">1. Preparing Your Development Computer</a></li> <li><a href="#Installing">2. Downloading the SDK Starter Package</a></li> <li><a href="#InstallingADT">3. Installing the ADT Plugin for Eclipse</a></li> - <li><a href="#AddingComponents">4. Adding Platforms and Other Components</a> + <li><a href="#AddingComponents">4. Adding Platforms and Other Packages</a> <ol> - <li><a href="#components">Available Components</a></li> - <li><a href="#which">Recommended Components</a></li> + <li><a href="#components">Available Packages</a></li> + <li><a href="#which">Recommended Packages</a></li> </ol></li> <li><a href="#sdkContents">5. Exploring the SDK (Optional)</a></li> <li><a href="#NextSteps">Next Steps</a></li> @@ -66,7 +66,7 @@ function toggleDiv(link) { <h2>See also</h2> <ol> <li><a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a></li> - <li><a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a></li> + <li><a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a></li> </ol> </div> @@ -81,9 +81,9 @@ this page.</p> <h4>Updating?</h4> -<p>If you already have an Android SDK, use the Android SDK and AVD Manager tool to install +<p>If you already have an Android SDK, use the Android SDK Manager tool to install updated tools and new Android platforms into your existing environment. For information about how to -do that, see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a>.</p> +do that, see <a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a>.</p> <h2 id="Preparing">Step 1. Preparing Your Development Computer</h2> @@ -111,7 +111,7 @@ RCP version of Eclipse is recommended.</p> <p>The SDK starter package is not a full development environment—it includes only the core SDK Tools, which you can -use to download the rest of the SDK components (such as the latest Android platform).</p> +use to download the rest of the SDK packages (such as the latest Android platform).</p> <p>If you haven't already, get the latest version of the SDK starter package from the <a href="{@docRoot}sdk/index.html">SDK download page</a>.</p> @@ -154,53 +154,53 @@ developing in Eclipse or other IDEs.</p> -<h2 id="AddingComponents">Step 4. Adding Platforms and Other Components</h2> +<h2 id="AddingComponents">Step 4. Adding Platforms and Other Packages</h2> -<p>The last step in setting up your SDK is using the Android SDK and AVD Manager (a -tool included in the SDK starter package) to download essential SDK components into your development +<p>The last step in setting up your SDK is using the Android SDK Manager (a +tool included in the SDK starter package) to download essential SDK packages into your development environment.</p> <p>The SDK uses a modular structure that separates the major parts of the SDK—Android platform versions, add-ons, tools, samples, and documentation—into a set of separately installable -components. The SDK starter package, which you've already downloaded, includes only a single -component: the latest version of the SDK Tools. To develop an Android application, you also need to +packages. The SDK starter package, which you've already downloaded, includes only a single +package: the latest version of the SDK Tools. To develop an Android application, you also need to download at least one Android platform and the associated platform tools. You can add other -components and platforms as well, which is highly recommended.</p> +packages and platforms as well, which is highly recommended.</p> <p>If you used the Windows installer, when you complete the installation wizard, it will launch the -Android SDK and AVD Manager with a default set of platforms and other components selected +Android SDK Manager with a default set of platforms and other packages selected for you to install. Simply click <strong>Install</strong> to accept the recommended set of -components and install them. You can then skip to <a href="#sdkContents">Step 5</a>, but we -recommend you first read the section about the <a href="#components">Available Components</a> to -better understand the components available from the Android SDK and AVD Manager.</p> +packages and install them. You can then skip to <a href="#sdkContents">Step 5</a>, but we +recommend you first read the section about the <a href="#components">Available Packages</a> to +better understand the packages available from the Android SDK Manager.</p> -<p>You can launch the Android SDK and AVD Manager in one of the following ways:</p> +<p>You can launch the Android SDK Manager in one of the following ways:</p> <ul> - <li>From within Eclipse, select <strong>Window > Android SDK and AVD Manager</strong>.</li> + <li>From within Eclipse, select <strong>Window > Android SDK Manager</strong>.</li> <li>On Windows, double-click the <code>SDK Manager.exe</code> file at the root of the Android SDK directory.</li> <li>On Mac or Linux, open a terminal and navigate to the <code>tools/</code> directory in the Android SDK, then execute: <pre>android</pre> </li> </ul> -<p>To download components, use the graphical UI of the Android SDK and AVD +<p>To download packages, use the graphical UI of the Android SDK Manager to browse the SDK repository and select new or updated -components (see figure 1). The Android SDK and AVD Manager installs the selected components in -your SDK environment. For information about which components you should download, see <a -href="#which">Recommended Components</a>.</p> +packages (see figure 1). The Android SDK Manager installs the selected packages in +your SDK environment. For information about which packages you should download, see <a +href="#which">Recommended Packages</a>.</p> <img src="/images/sdk_manager_packages.png" /> -<p class="img-caption"><strong>Figure 1.</strong> The Android SDK and AVD Manager's -<strong>Available Packages</strong> panel, which shows the SDK components that are +<p class="img-caption"><strong>Figure 1.</strong> The Android SDK Manager's +<strong>Available Packages</strong> panel, which shows the SDK packages that are available for you to download into your environment.</p> -<h3 id="components">Available Components</h3> +<h3 id="components">Available Packages</h3> -<p>By default, there are two repositories of components for your SDK: <em>Android +<p>By default, there are two repositories of packages for your SDK: <em>Android Repository</em> and <em>Third party Add-ons</em>.</p> -<p>The <em>Android Repository</em> offers these types of components:</p> +<p>The <em>Android Repository</em> offers these types of packages:</p> <ul> <li><strong>SDK Tools</strong> — Contains tools for debugging and testing your application @@ -219,9 +219,9 @@ developer guide.</li> <li><strong>Android platforms</strong> — An SDK platform is available for every production Android platform deployable to Android-powered devices. Each -SDK platform component includes a fully compliant Android library, system image, sample code, +SDK platform package includes a fully compliant Android library, system image, sample code, and emulator skins. To learn more about a specific platform, see the list of platforms that appears -under the section "Downloadable SDK Components" on the left part of this page.</li> +under the section "Downloadable SDK Packages" on the left part of this page.</li> <li><strong>USB Driver for Windows</strong> (Windows only) — Contains driver files that you can install on your Windows computer, so that you can run and debug @@ -243,16 +243,16 @@ tutorials. --></li> multiversion documentation for the Android framework API. </li> </ul> -<p>The <em>Third party Add-ons</em> provide components that allow you to create a development +<p>The <em>Third party Add-ons</em> provide packages that allow you to create a development environment using a specific Android external library (such as the Google Maps library) or a customized (but fully compliant) Android system image. You can add additional Add-on repositories by clicking <strong>Add Add-on Site</strong>.</p> -<h3 id="which">Recommended Components</h3> +<h3 id="which">Recommended Packages</h3> -<p>The SDK repository contains a range of components that you can download. -Use the table below to determine which components you need, based on whether you +<p>The SDK repository contains a range of packages that you can download. +Use the table below to determine which packages you need, based on whether you want to set up a basic, recommended, or full development environment: </p> @@ -260,7 +260,7 @@ want to set up a basic, recommended, or full development environment: <tr> <th>Environment</th> -<th>SDK Component</th> +<th>SDK Package</th> <th>Comments</th> </tr> @@ -268,8 +268,8 @@ want to set up a basic, recommended, or full development environment: <td rowspan="3" style="font-size:.9em;background-color:#FFE;">Basic</td> <td style="font-size:.9em;background-color:#FFE;">SDK Tools</td> <td style="font-size:.9em;background-color:#FFE;">If you've just installed -the SDK starter package, then you already have the latest version of this component. The -SDK Tools component is required to develop an Android application. Make sure you keep this up to +the SDK starter package, then you already have the latest version of this package. The +SDK Tools package is required to develop an Android application. Make sure you keep this up to date.</td> </tr> @@ -300,21 +300,21 @@ style="border:none"></td> <tr> <td rowspan="3">Recommended<br/>(plus Basic)</td> <td>Documentation</td> -<td>The Documentation component is useful because it lets you work offline and +<td>The Documentation package is useful because it lets you work offline and also look up API reference information from inside Eclipse.</td> </tr> <tr> <td>Samples</td> -<td>The Samples components give you source code that you can use to learn about +<td>The Samples packages give you source code that you can use to learn about Android, load as a project and run, or reuse in your own app. Note that multiple -samples components are available — one for each Android platform version. When -you are choosing a samples component to download, select the one whose API Level +samples packages are available — one for each Android platform version. When +you are choosing a samples package to download, select the one whose API Level matches the API Level of the Android platform that you plan to use.</td> </tr> <tr> <td>Usb Driver</td> -<td>The Usb Driver component is needed only if you are developing on Windows and +<td>The Usb Driver package is needed only if you are developing on Windows and have an Android-powered device on which you want to install your application for debugging and testing. For Mac OS X and Linux platforms, no special driver is needed.</td> @@ -344,12 +344,12 @@ applications on different platforms by running in an Android Virtual Device </table> -<p>Once you've installed at least the basic configuration of SDK components, you're ready to start +<p>Once you've installed at least the basic configuration of SDK packages, you're ready to start developing Android apps. The next section describes the contents of the Android SDK to familiarize -you with the components you've just installed.</p> +you with the packages you've just installed.</p> -<p>For more information about using the Android SDK and AVD Manager, see the <a -href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> document. </p> +<p>For more information about using the Android SDK Manager, see the <a +href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a> document. </p> <h2 id="sdkContents">Step 5. Exploring the SDK (Optional)</h2> @@ -358,7 +358,7 @@ href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a> document. and add-ons that you need, we suggest that you open the SDK directory and take a look at what's inside.</p> -<p>The table below describes the full SDK directory contents, with components +<p>The table below describes the full SDK directory contents, with packages installed. </p> <table> @@ -405,20 +405,21 @@ platform version.</td> <tr> <td colspan="3"><code>tools/</code></td> <td>Contains the set of development and profiling tools that are platform-independent, such -as the emulator, the Android SDK and AVD Manager, <code>ddms</code>, <code>hierarchyviewer</code> -and more. The tools in this directory may be updated at any time using the Android SDK and AVD +as the emulator, the Android SDK Manager, the AVD Manager, <code>ddms</code>, +<code>hierarchyviewer</code> +and more. The tools in this directory may be updated at any time using the Android SDK Manager and are independent of platform releases.</td> </tr> <tr> <td colspan="3"><code>SDK Readme.txt</code></td> <td>A file that explains how to perform the initial setup of your SDK, -including how to launch the Android SDK and AVD Manager tool on all +including how to launch the Android SDK Manager tool on all platforms.</td> </tr> <tr> <td colspan="3"><code>SDK Manager.exe</code></td> -<td>Windows SDK only. A shortcut that launches the Android SDK and AVD -Manager tool, which you use to add components to your SDK.</td> +<td>Windows SDK only. A shortcut that launches the Android SDK +Manager tool, which you use to add packages to your SDK.</td> </tr> <!--<tr> <td colspan="3"><code>documentation.html</code></td> @@ -531,7 +532,7 @@ second step in getting started with Android development. </p> <li>The Android SDK includes sample code and applications for each platform version. You can browse the samples in the <a href="{@docRoot}resources/index.html">Resources</a> tab or download them -into your SDK using the Android SDK and AVD Manager. Once you've downloaded the +into your SDK using the Android SDK Manager. Once you've downloaded the samples, you'll find them in <code><em><sdk></em>/samples/<em><platform>/</em></code>. </li> </ul> diff --git a/docs/html/sdk/ndk/index.jd b/docs/html/sdk/ndk/index.jd index 29f0749..6f06de3 100644 --- a/docs/html/sdk/ndk/index.jd +++ b/docs/html/sdk/ndk/index.jd @@ -1,16 +1,16 @@ ndk=true -ndk.win_download=android-ndk-r7b-windows.zip -ndk.win_bytes=80346206 -ndk.win_checksum=c42b0c9c14428397337421d5e4999380 +ndk.win_download=android-ndk-r7c-windows.zip +ndk.win_bytes=80361003 +ndk.win_checksum=e86184cdc4bf71d32fa9185fad8544e2 -ndk.mac_download=android-ndk-r7b-darwin-x86.tar.bz2 -ndk.mac_bytes=73817184 -ndk.mac_checksum=6daa82ca6b73bc0614c9997430079c7a +ndk.mac_download=android-ndk-r7c-darwin-x86.tar.bz2 +ndk.mac_bytes=73836512 +ndk.mac_checksum=025f57feb5f32ed993a5fa7f5996477d -ndk.linux_download=android-ndk-r7b-linux-x86.tar.bz2 -ndk.linux_bytes=64349733 -ndk.linux_checksum=0eb8af18796cdaa082df8f7c54ad7f9a +ndk.linux_download=android-ndk-r7c-linux-x86.tar.bz2 +ndk.linux_bytes=63432410 +ndk.linux_checksum=0bc21b78823dcf6f86b988203626b1fe page.title=Android NDK @@ -62,6 +62,59 @@ padding: .25em 1em; <div class="toggleable open"> <a href="#" onclick="return toggleDiv(this)"><img src= "{@docRoot}assets/images/triangle-opened.png" class="toggle-img" height="9px" width="9px"> + Android NDK, Revision 7c</a> <em>(March 2012)</em> + + <div class="toggleme"> + <p>This release of the NDK includes an important fix for Tegra2-based devices, and a few +additional fixes and improvements:</p> + + <dl> + <dt>Important bug fixes:</dt> + + <dd> + <ul> + <li>Fixed GNU STL armeabi-v7a binaries to not crash on non-NEON + devices. The files provided with NDK r7b were not configured properly, + resulting in crashes on Tegra2-based devices and others when trying to use + certain floating-point functions (e.g., {@code cosf}, {@code sinf}, {@code expf}).</li> + </ul> + </dd> + + <dt>Important changes:</dt> + + <dd> + <ul> + <li>Added support for custom output directories through the {@code NDK_OUT} + environment variable. When defined, this variable is used to store all + intermediate generated files, instead of {@code $PROJECT_PATH/obj}. The variable is + also recognized by {@code ndk-gdb}. </li> + <li>Added support for building modules with hundreds or even thousands of source + files by defining {@code LOCAL_SHORT_COMMANDS} to {@code true} in your {@code Android.mk}. + <p>This change forces the NDK build system to put most linker or archiver options + into list files, as a work-around for command-line length limitations. + See {@code docs/ANDROID-MK.html} for details.</p> + </li> + </ul> + </dd> + + <dt>Other bug fixes:</dt> + + <dd> + <ul> + <li>Fixed {@code android_getCpuCount()} implementation in the {@code cpufeatures} +helper library. On certain devices, where cores are enabled dynamically by the system, the previous +implementation would report the total number of <em>active</em> cores the first time the function +was called, rather than the total number of <em>physically available</em> cores.</li> + </ul> + </dd> + </dl> + </div> +</div> + + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"><img src= + "{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" width="9px"> Android NDK, Revision 7b</a> <em>(February 2012)</em> <div class="toggleme"> @@ -756,7 +809,7 @@ float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, <li>Includes improvements to the <code>cpufeatures</code> helper library that improves reporting of the CPU type (some devices previously reported ARMv7 CPU when the device really was an ARMv6). We recommend developers that use this library to rebuild their applications then - upload to Market to benefit from the improvements.</li> + upload to Google Play to benefit from the improvements.</li> <li>Adds an EGL library that lets you create and manage OpenGL ES textures and services.</li> @@ -832,7 +885,7 @@ float AMotionEvent_getHistoricalRawY(const AInputEvent* motion_event, <code>.apk</code>.</li> <li>To ensure that your applications are available to users only if their devices are - capable of running them, Android Market now filters applications based on the + capable of running them, Google Play now filters applications based on the instruction set information included in your application — no action is needed on your part to enable the filtering. Additionally, the Android system itself also checks your application at install time and allows the installation to continue only if the diff --git a/docs/html/sdk/ndk/overview.jd b/docs/html/sdk/ndk/overview.jd index e969f5d..c98e600 100644 --- a/docs/html/sdk/ndk/overview.jd +++ b/docs/html/sdk/ndk/overview.jd @@ -535,7 +535,7 @@ later)</li> <li>Additionally, an application using the OpenGL ES APIs should declare a <code><uses-feature></code> element in its manifest, with an <code>android:glEsVersion</code> attribute that specifies the minimum OpenGl ES version - required by the application. This ensures that Android Market will show your application only + required by the application. This ensures that Google Play will show your application only to users whose devices are capable of supporting your application. For example: <pre style="margin:1em;"> <manifest> diff --git a/docs/html/sdk/oem-usb.jd b/docs/html/sdk/oem-usb.jd index f98257d..88d66dd 100644 --- a/docs/html/sdk/oem-usb.jd +++ b/docs/html/sdk/oem-usb.jd @@ -34,7 +34,7 @@ To start developing with your device, read <a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a>.</p> <p class="note"><strong>Note:</strong> If your device is one of the Android Developer Phones -(purchased from the Android Market publisher site), a Nexus One, or a Nexus S, then you need +(ADP), a Nexus One, or a Nexus S, then you need the <a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a>, instead of an OEM driver. The Galaxy Nexus driver, however, is distributed by <a href="http://www.samsung.com/us/support/downloads/verizon-wireless/SCH-I515MSAVZW">Samsung</a> @@ -211,7 +211,7 @@ exact location of the <h2 id="Drivers">OEM Drivers</h2> <p class="note"><strong>Note:</strong> If your device is one of the Android Developer Phones -(purchased from the Android Market publisher site), a Nexus One, or a Nexus S, then you need +(purchased from the Google Play publisher site), a Nexus One, or a Nexus S, then you need the <a href="{@docRoot}sdk/win-usb.html">Google USB Driver</a>, instead of an OEM driver. The Galaxy Nexus driver, however, is distributed by <a href="http://www.samsung.com/us/support/downloads/verizon-wireless/SCH-I515MSAVZW">Samsung</a> @@ -314,6 +314,10 @@ href="http://developer.sonyericsson.com/wportal/devworld/search-downloads/driver href="http://www.teleepoch.com/android.html">http://www.teleepoch.com/android.html</a></td> </tr> +<tr><td>Yulong Coolpad</td> <td><a +href="http://www.yulong.com/product/product/product/downloadList.html#downListUL">http://www.yulong.com/product/product/product/downloadList.html#downListUL</a></td> +</tr> + <tr> <td>ZTE</td> <td><a href="http://support.zte.com.cn/support/news/NewsDetail.aspx?newsId=1000442">http://support.zte.com.cn/support/news/NewsDetail.aspx?newsId=1000442</a></td></tr> diff --git a/docs/html/sdk/requirements.jd b/docs/html/sdk/requirements.jd index c970f6c..c76e8c8 100644 --- a/docs/html/sdk/requirements.jd +++ b/docs/html/sdk/requirements.jd @@ -24,7 +24,7 @@ Android applications using the Android SDK. </p> <h4 style="margin-top:.25em"><em>Eclipse IDE</em></h4> <ul> - <li>Eclipse 3.6 (Helios) or greater + <li>Eclipse 3.6.2 (Helios) or greater <p class="note"><strong>Note:</strong> Eclipse 3.5 (Galileo) is no longer supported with the latest version of ADT.</p></li> <li>Eclipse <a href="http://www.eclipse.org/jdt">JDT</a> plugin (included @@ -41,8 +41,8 @@ packages: </p> <li>Eclipse IDE for Java EE Developers</li> </ul> </li> - <li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK 5 or JDK -6</a> (JRE alone is not sufficient)</li> + <li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK 6</a> + (JRE alone is not sufficient)</li> <li><a href="eclipse-adt.html">Android Development Tools plugin</a> (recommended)</li> <li><strong>Not</strong> compatible with Gnu Compiler for Java (gcj)</li> @@ -51,8 +51,8 @@ packages: </p> <h4><em>Other development environments or IDEs</em></h4> <ul> - <li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK 5 or JDK -6</a> (JRE alone is not sufficient)</li> + <li><a href="http://www.oracle.com/technetwork/java/javase/downloads/index.html">JDK 6</a> + (JRE alone is not sufficient)</li> <li><a href="http://ant.apache.org/">Apache Ant</a> 1.8 or later</li> <li><strong>Not</strong> compatible with Gnu Compiler for Java (gcj)</li> </ul> diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index f7541f7..3aafea9 100644 --- a/docs/html/sdk/sdk_toc.cs +++ b/docs/html/sdk/sdk_toc.cs @@ -40,8 +40,7 @@ <li> <span class="heading">Android 3.0 Preview SDK</span> <ul> - <li><a href="<?cs var:toroot ?>sdk/preview/start.html">Getting Started</a> <span -class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>sdk/preview/start.html">Getting Started</a></li> </ul> </li><?cs /if ?> @@ -55,7 +54,7 @@ class="new">new!</span></li> /if ?> <li> <span class="heading"> - <span class="en">Downloadable SDK Components</span> + <span class="en">Downloadable SDK Packages</span> <span style="display:none" class="de"></span> <span style="display:none" class="es"></span> <span style="display:none" class="fr"></span> @@ -66,7 +65,7 @@ class="new">new!</span></li> </span> <ul> <li><a href="<?cs var:toroot ?>sdk/adding-components.html"> - <span class="en">Adding SDK Components</span> + <span class="en">Adding SDK Packages</span> <span style="display:none" class="de"></span> <span style="display:none" class="es"></span> <span style="display:none" class="fr"></span> @@ -79,9 +78,9 @@ class="new">new!</span></li> <ul> <li class="toggle-list"> <div><a href="<?cs var:toroot ?>sdk/android-4.0-highlights.html"> - <span class="en">Android 4.0.x Platform</span></a> <span class="new">new!</span></div> + <span class="en">Android 4.0.x Platform</span></a></div> <ul> - <li><a href="<?cs var:toroot ?>sdk/android-4.0.3.html">Android 4.0.3 Platform</a> <span class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>sdk/android-4.0.3.html">Android 4.0.3 Platform</a></li> <li><a href="<?cs var:toroot ?>sdk/android-4.0.html">Android 4.0 Platform</a> </li> </ul> </li> @@ -152,11 +151,9 @@ class="new">new!</span></li> </li> </ul> <ul> - <li><a href="<?cs var:toroot ?>sdk/tools-notes.html">SDK Tools, r16</a> <span -class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>sdk/tools-notes.html">SDK Tools, r18</a></li> <li><a href="<?cs var:toroot ?>sdk/win-usb.html">Google USB Driver, r4</a></li> - <li><a href="<?cs var:toroot ?>sdk/compatibility-library.html">Support Package, r6</a> - <span class="new">new!</span></li> + <li><a href="<?cs var:toroot ?>sdk/compatibility-library.html">Support Package, r7</a></li> </ul> </li> <li> @@ -171,15 +168,14 @@ class="new">new!</span></li> <span style="display:none" class="zh-TW"></span> </span> <ul> - <li><a href="<?cs var:toroot ?>sdk/eclipse-adt.html">ADT 16.0.1 + <li><a href="<?cs var:toroot ?>sdk/eclipse-adt.html">ADT 18.0.0 <span style="display:none" class="de"></span> <span style="display:none" class="es"></span> <span style="display:none" class="fr"></span> <span style="display:none" class="it"></span> <span style="display:none" class="ja"></span> <span style="display:none" class="zh-CN"></span> - <span style="display:none" class="zh-TW"></span></a> <span -class="new">new!</span> + <span style="display:none" class="zh-TW"></span></a> </li> </ul> </li> @@ -195,7 +191,7 @@ class="new">new!</span> <span style="display:none" class="zh-TW"></span> </span> <ul> - <li><a href="<?cs var:toroot ?>sdk/ndk/index.html">Android NDK, r7b</a> + <li><a href="<?cs var:toroot ?>sdk/ndk/index.html">Android NDK, r7c</a> <span class="new">new!</span> </li> <li><a href="<?cs var:toroot ?>sdk/ndk/overview.html">What is the NDK?</a></li> diff --git a/docs/html/sdk/tools-notes.jd b/docs/html/sdk/tools-notes.jd index 91bcb7d..f4e9d4d 100644 --- a/docs/html/sdk/tools-notes.jd +++ b/docs/html/sdk/tools-notes.jd @@ -64,11 +64,156 @@ padding: .25em 1em; } </style> - <div class="toggleable opened"> <a href="#" onclick="return toggleDiv(this)"> <img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-img" height="9px" width="9px" /> + SDK Tools, Revision 18</a> <em>(April 2012)</em> + + <div class="toggleme"> + <p class="caution"><strong>Important:</strong> To download the new Android + 4.0 system components from the Android SDK Manager, you must first update the + SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, + the Android 4.0 system components will not be available for download.</p> + + <dl> + <dt>Dependencies:</dt> + <dd> + <ul> + <li>Android SDK Platform-tools revision 9 or later.</li> + <li>If you are developing in Eclipse with ADT, note that the SDK Tools r18 is designed for + use with ADT 18.0.0 and later. If you haven't already, we highly recommend updating your + <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin</a> to 18.0.0.</li> + <li>If you are developing outside Eclipse, you must have + <a href="http://ant.apache.org/">Apache Ant</a> 1.8 or later.</li> + </ul> + </dd> + <dt>General notes:</dt> + <dd> + <ul> + <li>Updated the SdkController app to encapsulate both sensor and multitouch emulation + functionality.</li> + </ul> + </dd> + <dt>Bug fixes:</dt> + <dd> + <ul> + <li>Fixed Ant issues where some jar libraries in the {@code libs/} folder are not picked up +in some cases.</li> + </ul> + </dd> + </dl> + </div> +</div> + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" + width="9px" /> + SDK Tools, Revision 17</a> <em>(March 2012)</em> + + <div class="toggleme"> + <p class="caution"><strong>Important:</strong> To download the new Android + 4.0 system components from the Android SDK Manager, you must first update the + SDK tools to revision 14 or later and restart the Android SDK Manager. If you do not, + the Android 4.0 system components will not be available for download.</p> + + <dl> + <dt>Dependencies:</dt> + <dd> + <ul> + <li>Android SDK Platform-tools revision 9 or later.</li> + <li>If you are developing in Eclipse with ADT, note that the SDK Tools r17 is designed for + use with ADT 17.0.0 and later. If you haven't already, we highly recommend updating your + <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin</a> to 17.0.0.</li> + <li>If you are developing outside Eclipse, you must have + <a href="http://ant.apache.org/">Apache Ant</a> 1.8 or later.</li> + </ul> + </dd> + <dt>General notes:</dt> + <dd> + <ul> + <li>Emulator + <ul> + <li>Added support for hardware accelerated graphics rendering. This feature requires an +API Level 15, Revision 3 or later system image. +(<a href="{@docRoot}guide/developing/devices/emulator.html#accel-graphics">more info</a>) + </li> + <li>Added support for running Android x86 system images in virtualization mode on +Windows and Mac OS X. +(<a href="{@docRoot}guide/developing/devices/emulator.html#accel-vm">more info</a>) + <p class="note"><strong>Note:</strong> Use the Android SDK Manager to download and +install x86 system images. Android x86 system images are not available for all API levels.</p> + </li> + <li>Added experimental support for multi-touch input by enabing the emulator to receive + touch input from a USB-tethered physical Android device. + (<a href="http://tools.android.com/tips/hardware-emulation">more info</a>)</li> + </ul> + </li> + <li>Added viewing of live detailed network usage of an app in DDMS. (<a + href="http://tools.android.com/recent/detailednetworkusageinddms">more info</a>)</li> + <li>ProGuard + <ul> + <li>Updated the bundled ProGuard tool to version 4.7. In addition to many new features, +this update fixes the {@code Conversion to Dalvik format failed with error 1} error some users have +experienced.</li> + <li>Updated the default {@code proguard.cfg} file with better default flags for + Android.</li> + <li>Split the ProGuard configuration file has been in half, with project specific flags +kept in project and the generic Android flags distributed (and updated) with the tools +themselves.</li> + </ul> + </li> + <li>Build + <ul> + <li>Added a feature that allows you to run some code only in debug mode. Builds now +generate a class called {@code BuildConfig} containing a {@code DEBUG} constant that is +automatically set according to your build type. You can check the ({@code BuildConfig.DEBUG}) +constant in your code to run debug-only functions.</li> + <li>Fixed issue when a project and its libraries include the same jar file in their libs + folder. (<a href="http://tools.android.com/recent/dealingwithdependenciesinandroidprojects">more + info</a>)</li> + <li>Added support for custom views with custom attributes in libraries. Layouts using +custom attributes must use the namespace URI {@code http://schemas.android.com/apk/res-auto} instead +of the URI that includes the app package name. This URI is replaced with the app specific one at +build time.</li> + </ul> + </li> + <li>Lint + <ul> + <li>Updated Lint to check Android application code. Lint rules which previously +performed pattern based searches in the application code (such as the unused resource check) have +been rewritten to use the more accurate Java-style parse trees.</li> + <li>Added support for checking library projects. This change means that rules such as +the unused resource check properly handle resources declared in a library project and referenced in +a downstream project.</li> + <li>Added ability to suppress Lint warnings in Java code with the new +{@code @SuppressLint} annotation, and in XML files with the new tools: namespace and +ignore attribute. (<a + href="http://tools.android.com/recent/ignoringlintwarnings">more info</a>)</li> + <li>New Lint checks: + <ul> + <li>Added check for Android API calls that require a version of Android higher than + the minimum supported version. You can use the new {@code @TargetApi} annotation + to suppress warnings when the code is wrapped in a system version condition. + (<a href="http://tools.android.com/recent/lintapicheck">more info</a>)</li> + <li>Added over 20 new Lint rules, including checks for + <a href="http://tools.android.com/recent/lintperformancechecks">performance</a>, + XML layouts, manifest and file handling.</li> + </ul> + </li> + </ul> + </li> + </ul> + </dd> + </dl> + </div> +</div> + +<div class="toggleable closed"> + <a href="#" onclick="return toggleDiv(this)"> + <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-img" height="9px" + width="9px" /> SDK Tools, Revision 16</a> <em>(December 2011)</em> <div class="toggleme"> @@ -92,10 +237,10 @@ padding: .25em 1em; <dt>General notes:</dt> <dd> <ul> - <li>Added Lint tools to detect common errors in Android projects. + <li>Added Lint tools to detect common errors in Android projects. (<a href="http://tools.android.com/recent/lint">more info</a>)</li> <li>Added sensor emulation support, which allows the emulator to read sensor data from a - physical Android device. + physical Android device. (<a href="http://tools.android.com/recent/sensoremulation">more info</a>)</li> <li>Added support for using a webcam to emulate a camera on Mac OS X.</li> </ul> diff --git a/docs/html/sdk/win-usb.jd b/docs/html/sdk/win-usb.jd index 2bd031e..3be0faf 100644 --- a/docs/html/sdk/win-usb.jd +++ b/docs/html/sdk/win-usb.jd @@ -12,7 +12,7 @@ page.title=Google USB Driver <ol> <li><a href="{@docRoot}sdk/oem-usb.html#InstallingDriver">Installing a USB Driver</a></li> <li><a href="{@docRoot}guide/developing/device.html">Using Hardware Devices</a></li> - <li><a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a></li> + <li><a href="{@docRoot}sdk/adding-components.html">Adding SDK Packages</a></li> </ol> </div> </div> @@ -51,7 +51,7 @@ for Windows. </p> <p>The sections below provide notes about successive revisions of the USB Driver for Windows, as denoted by revision number. To determine what revision of the USB Driver for Windows you are using, refer to the "Installed Packages" listing -in the Android SDK and AVD Manager.</p> +in the Android SDK Manager.</p> <script type="text/javascript"> function toggleDiv(link) { @@ -147,9 +147,9 @@ for the T-Mobile G1 and myTouch 3G (and similar devices).</p></dt> <h2 id="WinUsbDriver">Downloading the Google USB Driver</h2> -<div class="figure" style="width:498px;margin:0"> +<div class="figure" style="width:536px;margin:0"> <img src="{@docRoot}images/developing/sdk-usb-driver.png" alt="" /> - <p class="img-caption"><strong>Figure 1.</strong> The SDK and AVD Manager + <p class="img-caption"><strong>Figure 1.</strong> The SDK Manager with the Google USB Driver selected.</p> </div> @@ -158,10 +158,10 @@ component. You need the driver only if you are developing on Windows and want to connect an Android-powered device (ADP, Nexus One, or Nexus S) to your development environment over USB. </p> -<p>To download the driver, use the Android SDK and AVD Manager tool that is +<p>To download the driver, use the Android SDK Manager tool that is included with the <a href="{@docRoot}sdk/index.html">Android SDK</a>:</p> <ol> - <li>Launch the SDK and AVD Manager by double-clicking <code>SDK Manager.exe</code>, + <li>Launch the Android SDK Manager by double-clicking <code>SDK Manager.exe</code>, at the root of your SDK directory.</li> <li>Expand <em>Extras</em>.</li> <li>Check <strong>Google USB Driver package</strong> and click <strong>Install</strong>.</li> diff --git a/docs/html/shareables/training/BitmapFun.zip b/docs/html/shareables/training/BitmapFun.zip Binary files differnew file mode 100644 index 0000000..e7e71f9 --- /dev/null +++ b/docs/html/shareables/training/BitmapFun.zip diff --git a/docs/html/shareables/training/LocationAware.zip b/docs/html/shareables/training/LocationAware.zip Binary files differnew file mode 100644 index 0000000..46970cd --- /dev/null +++ b/docs/html/shareables/training/LocationAware.zip diff --git a/docs/html/sitemap.txt b/docs/html/sitemap.txt index cfbda2b..3f26dd0 100644 --- a/docs/html/sitemap.txt +++ b/docs/html/sitemap.txt @@ -108,7 +108,7 @@ http://developer.android.com/guide/topics/testing/activity_testing.html http://developer.android.com/guide/topics/testing/contentprovider_testing.html http://developer.android.com/guide/topics/testing/service_testing.html http://developer.android.com/guide/topics/testing/what_to_test.html -http://developer.android.com/guide/publishing/licensing.html +http://developer.android.com/guide/market/licensing/index.html http://developer.android.com/guide/market/billing/index.html http://developer.android.com/guide/market/billing/billing_about.html http://developer.android.com/guide/market/billing/billing_overview.html @@ -160,8 +160,6 @@ http://developer.android.com/guide/practices/ui_guidelines/icon_design_tab.html http://developer.android.com/guide/practices/ui_guidelines/icon_design_dialog.html http://developer.android.com/guide/practices/ui_guidelines/icon_design_list.html http://developer.android.com/guide/practices/ui_guidelines/widget_design.html -http://developer.android.com/guide/practices/ui_guidelines/activity_task_design.html -http://developer.android.com/guide/practices/ui_guidelines/menu_design.html http://developer.android.com/guide/practices/design/performance.html http://developer.android.com/guide/practices/design/responsiveness.html http://developer.android.com/guide/practices/design/seamlessness.html diff --git a/docs/html/training/accessibility/accessible-app.jd b/docs/html/training/accessibility/accessible-app.jd new file mode 100644 index 0000000..f4087b8 --- /dev/null +++ b/docs/html/training/accessibility/accessible-app.jd @@ -0,0 +1,194 @@ + +page.title=Developing Accessible Applications +parent.title=Implementing Accessibility +parent.link=index.html + +trainingnavtop=true +next.title=Developing an Accessibility Service +next.link=service.html + +@jd:body + + + + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#contentdesc">Add Content Descriptions</a></li> + <li><a href="#focus">Design for Focus Navigation</a></li> + <li><a href="#events">Fire Accessibility Events</a></li> + <li><a href="#testing">Test Your Application</a></li> +</ol> + +<!-- other docs (NOT javadocs) --> +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/ui/accessibility/apps.html">Making + Applications Accessible</a></li> +</ul> + + +</div> +</div> + +<p>Android has several accessibility-focused features baked into the platform, +which make it easy to optimize your application for those with visual or +physical disabilities. However, it's not always obvious what the correct +optimizations are, or the easiest way to leverage the framework toward this +purpose. This lesson shows you how to implement the strategies and platform +features that make for a great accessibility-enabled Android application.</p> + +<h2 id="contentdesc">Add Content Descriptions</h2> +<p>A well-designed user interface (UI) often has elements that don't require an explicit +label to indicate their purpose to the user. A checkbox next to an item in a +task list application has a fairly obvious purpose, as does a trash can in a file +manager application. However, to your users with vision impairment, other UI +cues are needed.</p> + +<p>Fortunately, it's easy to add labels to UI elements in your application that +can be read out loud to your user by a speech-based accessibility service like <a + href="https://market.android.com/details?id=com.google.android.marvin.talkback">TalkBack</a>. +If you have a label that's likely not to change during the lifecycle of the +application (such as "Pause" or "Purchase"), you can add it via the XML layout, +by setting a UI element's <a + href="{@docRoot}reference/android/view.View#attr_android:contentDescription">android:contentDescription</a> attribute, like in this +example:</p> +<pre> +<Button + android:id=”@+id/pause_button” + android:src=”@drawable/pause” + android:contentDescription=”@string/pause”/> +</pre> + +<p>However, there are plenty of situations where it's desirable to base the content +description on some context, such as the state of a toggle button, or a piece +selectable data like a list item. To edit the content description at runtime, +use the {@link android.view.View#setContentDescription(CharSequence) +setContentDescription()} method, like this:</p> + +<pre> +String contentDescription = "Select " + strValues[position]; +label.setContentDescription(contentDescription); +</pre> + +<p>This addition to your code is the simplest accessibility improvement you can make to your +application, but one of the most useful. Try to add content descriptions +wherever there's useful information, but avoid the web-developer pitfall of +labelling <em>everything</em> with useless information. For instance, don't set +an application icon's content description to "app icon". That just increases +the noise a user needs to navigate in order to pull useful information from your +interface.</p> + +<p>Try it out! Download <a + href="https://market.android.com/details?id=com.google.android.marvin.talkback">TalkBack</a> +(an accessibility service published by Google) and enable it in <strong>Settings + > Accessibility > TalkBack</strong>. Then navigate around your own +application and listen for the audible cues provided by TalkBack.</p> + +<h2 id="focus">Design for Focus Navigation</h2> +<p>Your application should support more methods of navigation than the +touch screen alone. Many Android devices come with navigation hardware other +than the touchscreen, like a D-Pad, arrow keys, or a trackball. In addition, +later Android releases also support connecting external devices like keyboards +via USB or bluetooth.</p> + +<p>In order to enable this form of navigation, all navigational elements that +the user should be able to navigate to need to be set as focusable. This +modification can be +done at runtime using the +{@link android.view.View#setFocusable View.setFocusable()} method on that UI +control, or by setting the <a + href="{@docRoot}android.view.View#attr_android:focusable">{@code + android:focusable}</a> +attrubute in your XML layout files.</p> + +<p>Also, each UI control has 4 attributes, +<a href="{@docRoot}reference/android/view/View#attr_android:nextFocusUp">{@code + android:nextFocusUp}</a>, +<a + href="{@docRoot}reference/android/view/View#attr_android:nextFocusDown">{@code + android:nextFocusDown}</a>, +<a + href="{@docRoot}reference/android/view/View#attr_android:nextFocusLeft">{@code + android:nextFocusLeft}</a>, +and <a + href="{@docRoot}reference/android/view/View#attr_android:nextFocusRight">{@code + android:nextFocusRight}</a>, +which you can use to designate +the next view to receive focus when the user navigates in that direction. While +the platform determines navigation sequences automatically based on layout +proximity, you can use these attributes to override that sequence if it isn't +appropriate in your application. </p> + +<p>For instance, here's how you represent a button and label, both +focusable, such that pressing down takes you from the button to the text view, and +pressing up would take you back to the button.</p> + + +<pre> +<Button android:id="@+id/doSomething" + android:focusable="true" + android:nextFocusDown=”@id/label” + ... /> +<TextView android:id="@+id/label" + android:focusable=”true” + android:text="@string/labelText" + android:nextFocusUp=”@id/doSomething” + ... /> +</pre> + +<p>Verify that your application works intuitively in these situations. The +easiest way is to simply run your application in the Android emulator, and +navigate around the UI with the emulator's arrow keys, using the OK button as a +replacement for touch to select UI controls.</p> + +<h2 id="events">Fire Accessibility Events</h2> +<p>If you're using the view components in the Android framework, an +{@link android.view.accessibility.AccessibilityEvent} is created whenever you +select an item or change focus in your UI. These events are examined by the +accessibility service, enabling it to provide features like text-to-speech to +the user.</p> + +<p>If you write a custom view, make sure it fires events at the appropriate +times. Generate events by calling {@link +android.view.View#sendAccessibilityEvent(int)}, with a parameter representing +the type of event that occurred. A complete list of the event types currently +supported can be found in the {@link +android.view.accessibility.AccessibilityEvent} reference documentation. + +<p>As an example, if you want to extend an image view such that you can write +captions by typing on the keyboard when it has focus, it makes sense to fire an +{@link android.view.accessibility.AccessibilityEvent#TYPE_VIEW_TEXT_CHANGED} +event, even though that's not normally built into image views. The code to +generate that event would look like this:</p> +<pre> +public void onTextChanged(String before, String after) { + ... + if (AccessibilityManager.getInstance(mContext).isEnabled()) { + sendAccessibilityEvent(AccessibilityEvent.TYPE_VIEW_TEXT_CHANGED); + } + ... +} +</pre> + +<h2 id="testing">Test Your Application</h2> +<p>Be sure to test the accessibility functionality as you add it to your +application. In order to test the content descriptions and Accessibility +events, install and enable an accessibility service. One option is <a + href="https://play.google.com/store/details?id=com.google.android.marvin.talkback">Talkback</a>, +a free, open source screen reader available on Google Play. With the service +enabled, test all the navigation flows through your application and listen to +the spoken feedback.</p> + +<p>Also, attempt to navigate your application using a directional controller, +instead of the touch screen. You can use a physical device with a d-pad or +trackball if one is available. If not, use the Android emulator and it's +simulated keyboard controls.</p> + +<p>Between the service providing feedback and the directional navigation through +your application, you should get a sense of what your application is like to +navigate without any visual cues. Fix problem areas as they appear, and you'll +end up with with a more accessible Android application.</p> diff --git a/docs/html/training/accessibility/index.jd b/docs/html/training/accessibility/index.jd new file mode 100644 index 0000000..333f9f2 --- /dev/null +++ b/docs/html/training/accessibility/index.jd @@ -0,0 +1,55 @@ +page.title=Implementing Accessibility + +trainingnavtop=true +startpage=true +next.title=Developing Accessible Applications +next.link=accessible-app.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 2.0 (API Level 5) or higher</li> +</ul> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/ui/accessibility/index.html">Accessibility</a></li> +</ul> + +</div> +</div> + +<p>When it comes to reaching as wide a userbase as possible, it's important to +pay attention to accessibility in your Android application. Cues in your user +interface that may work for a majority of users, such as a visible change in +state when a button is pressed, can be less optimal if the user is visually +impaired.</p> + +<p>This class shows you how to make the most of the accessibility features +built into the Android framework. It covers how to optimize your app for +accessibility, leveraging platform features like focus navigation and content +descriptions. It also covers how to build accessibility services, that can +facilitate user interaction with <strong>any</strong> Android application, not +just your own.</p> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="accessible-app.html">Developing Accessible Applications</a></b></dt> + <dd>Learn to make your Android application accessible. Allow for easy + navigation with a keyboard or directional pad, set labels and fire events + that can be interpreted by an accessibility service to facilitate a smooth + user experience.</dd> + + <dt><b><a href="service.html">Developing Accessibility Services</a></b></dt> + <dd>Develop an accessibility service that listens for accessibility events, + mines those events for information like event type and content descriptions, + and uses that information to communicate with the user. The example will + use a text-to-speech engine to speak to the user.</dd> + +</dl> + diff --git a/docs/html/training/accessibility/service.jd b/docs/html/training/accessibility/service.jd new file mode 100644 index 0000000..f62506b --- /dev/null +++ b/docs/html/training/accessibility/service.jd @@ -0,0 +1,286 @@ + +page.title=Developing an Accessibility Service +parent.title=Implementing Accessibility +parent.link=index.html + +trainingnavtop=true +previous.title=Developing Accessible Applications +previous.link=accessible-app.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#create">Create Your Accessibility Service</a></li> + <li><a href="#configure">Configure Your Accessibility Service</a></li> + <li><a href="#events">Respond to AccessibilityEvents</a></li> + <li><a href="#query">Query the View Heirarchy for More Context</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/ui/accessibility/services.html">Building + Accessibility Services</a></li> +</ul> + +</div> +</div> + + +<p>Accessibility services are a feature of the Android framework designed to +provide alternative navigation feedback to the user on behalf of applications +installed on Android devices. An accessibility service can communicate to the +user on the application's behalf, such as converting text to speech, or haptic +feedback when a user is hovering on an important area of the screen. This +lesson covers how to create an accessibility service, process information +received from the application, and report that information back to the +user.</p> + + +<h2 id="create">Create Your Accessibility Service</h2> +<p>An accessibility service can be bundled with a normal application, or created +as a standalone Android project. The steps to creating the service are the same +in either situation. Within your project, create a class that extends {@link +android.accessibilityservice.AccessibilityService}.</p> + +<pre> +package com.example.android.apis.accessibility; + +import android.accessibilityservice.AccessibilityService; + +public class MyAccessibilityService extends AccessibilityService { +... + @Override + public void onAccessibilityEvent(AccessibilityEvent event) { + } + + @Override + public void onInterrupt() { + } + +... +} +</pre> + +<p>Like any other service, you also declare it in the manifest file. +Remember to specify that it handles the {@code android.accessibilityservice} intent, +so that the service is called when applications fire an +{@link android.view.accessibility.AccessibilityEvent}.</p> + +<pre> +<application ...> +... +<service android:name=".MyAccessibilityService"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + . . . +</service> +... +</application> +</pre> + +<p>If you created a new project for this service, and don't plan on having an +application, you can remove the starter Activity class (usually called MainActivity.java) from your source. Remember to +also remove the corresponding activity element from your manifest.</p> + +<h2 id="configure">Configure Your Accessibility Service</h2> +<p>Setting the configuration variables for your accessibility service tells the +system how and when you want it to run. Which event types would you like to +respond to? Should the service be active for all applications, or only specific +package names? What different feedback types does it use?</p> + +<p>You have two options for how to set these variables. The +backwards-compatible option is to set them in code, using {@link +android.accessibilityservice.AccessibilityService#setServiceInfo(android.accessibilityservice.AccessibilityServiceInfo)}. +To do that, override the {@link +android.accessibilityservice.AccessibilityService#onServiceConnected()} method +and configure your service in there.</p> + +<pre> +@Override +public void onServiceConnected() { + // Set the type of events that this service wants to listen to. Others + // won't be passed to this service. + info.eventTypes = AccessibilityEvent.TYPE_VIEW_CLICKED | + AccessibilityEvent.TYPE_VIEW_FOCUSED; + + // If you only want this service to work with specific applications, set their + // package names here. Otherwise, when the service is activated, it will listen + // to events from all applications. + info.packageNames = new String[] + {"com.example.android.myFirstApp", "com.example.android.mySecondApp"}; + + // Set the type of feedback your service will provide. + info.feedbackType = AccessibilityServiceInfo.FEEDBACK_SPOKEN; + + // Default services are invoked only if no package-specific ones are present + // for the type of AccessibilityEvent generated. This service *is* + // application-specific, so the flag isn't necessary. If this was a + // general-purpose service, it would be worth considering setting the + // DEFAULT flag. + + // info.flags = AccessibilityServiceInfo.DEFAULT; + + info.notificationTimeout = 100; + + this.setServiceInfo(info); + +} +</pre> + +<p>Starting with Android 4.0, there is a second option available: configure the +service using an XML file. Certain configuration options like +{@link android.R.attr#canRetrieveWindowContent} are only available if you +configure your service using XML. The same configuration options above, defined +using XML, would look like this:</p> + +<pre> +<accessibility-service + android:accessibilityEventTypes="typeViewClicked|typeViewFocused" + android:packageNames="com.example.android.myFirstApp, com.example.android.mySecondApp" + android:accessibilityFeedbackType="feedbackSpoken" + android:notificationTimeout="100" + android:settingsActivity="com.example.android.apis.accessibility.TestBackActivity" + android:canRetrieveWindowContent="true" +/> +</pre> + +<p>If you go the XML route, be sure to reference it in your manifest, by adding +a <a +href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a> tag to +your service declaration, pointing at the XML file. If you stored your XML file +in {@code res/xml/serviceconfig.xml}, the new tag would look like this:</p> + +<pre> +<service android:name=".MyAccessibilityService"> + <intent-filter> + <action android:name="android.accessibilityservice.AccessibilityService" /> + </intent-filter> + <meta-data android:name="android.accessibilityservice" + android:resource="@xml/serviceconfig" /> +</service> +</pre> + +<h2 id="events">Respond to AccessibilityEvents</h2> +<p>Now that your service is set up to run and listen for events, write some code +so it knows what to do when an {@link +android.view.accessibility.AccessibilityEvent} actually arrives! Start by +overriding the {@link +android.accessibilityservice.AccessibilityService#onAccessibilityEvent} method. +In that method, use {@link +android.view.accessibility.AccessibilityEvent#getEventType} to determine the +type of event, and {@link +android.view.accessibility.AccessibilityEvent#getContentDescription} to extract +any label text associated with the fiew that fired the event.</pre> + +<pre> +@Override +public void onAccessibilityEvent(AccessibilityEvent event) { + final int eventType = event.getEventType(); + String eventText = null; + switch(eventType) { + case AccessibilityEvent.TYPE_VIEW_CLICKED: + eventText = "Focused: "; + break; + case AccessibilityEvent.TYPE_VIEW_FOCUSED: + eventText = "Focused: "; + break; + } + + eventText = eventText + event.getContentDescription(); + + // Do something nifty with this text, like speak the composed string + // back to the user. + speakToUser(eventText); + ... +} +</pre> + +<h2 id="query">Query the View Heirarchy for More Context</h2> +<p>This step is optional, but highly useful. One of the new features in Android +4.0 (API Level 14) is the ability for an +{@link android.accessibilityservice.AccessibilityService} to query the view +hierarchy, collecting information about the the UI component that generated an event, and +its parent and children. In order to do this, make sure that you set the +following line in your XML configuration:</p> +<pre> +android:canRetrieveWindowContent="true" +</pre> +<p>Once that's done, get an {@link +android.view.accessibility.AccessibilityNodeInfo} object using {@link +android.view.accessibility.AccessibilityEvent#getSource}. This call only +returns an object if the window where the event originated is still the active +window. If not, it will return null, so <em>behave accordingly</em>. The +following example is a snippet of code that, when it receives an event, does +the following: +<ol> + <li>Immediately grab the parent of the view where the event originated</li> + <li>In that view, look for a label and a check box as children views</li> + <li>If it finds them, create a string to report to the user, indicating + the label and whether it was checked or not.</li> + <li>If at any point a null value is returned while traversing the view + hierarchy, the method quietly gives up.</li> +</ol> + +<pre> + +// Alternative onAccessibilityEvent, that uses AccessibilityNodeInfo + +@Override +public void onAccessibilityEvent(AccessibilityEvent event) { + + AccessibilityNodeInfo source = event.getSource(); + if (source == null) { + return; + } + + // Grab the parent of the view that fired the event. + AccessibilityNodeInfo rowNode = getListItemNodeInfo(source); + if (rowNode == null) { + return; + } + + // Using this parent, get references to both child nodes, the label and the checkbox. + AccessibilityNodeInfo labelNode = rowNode.getChild(0); + if (labelNode == null) { + rowNode.recycle(); + return; + } + + AccessibilityNodeInfo completeNode = rowNode.getChild(1); + if (completeNode == null) { + rowNode.recycle(); + return; + } + + // Determine what the task is and whether or not it's complete, based on + // the text inside the label, and the state of the check-box. + if (rowNode.getChildCount() < 2 || !rowNode.getChild(1).isCheckable()) { + rowNode.recycle(); + return; + } + + CharSequence taskLabel = labelNode.getText(); + final boolean isComplete = completeNode.isChecked(); + String completeStr = null; + + if (isComplete) { + completeStr = getString(R.string.checked); + } else { + completeStr = getString(R.string.not_checked); + } + String reportStr = taskLabel + completeStr; + speakToUser(reportStr); +} + +</pre> + +<p>Now you have a complete, functioning accessibility service. Try configuring +how it interacts with the user, by adding Android's <a + href="http://developer.android.com/resources/articles/tts.html">text-to-speech + engine</a>, or using a {@link android.os.Vibrator} to provide haptic +feedback!</p> diff --git a/docs/html/training/camera/cameradirect.jd b/docs/html/training/camera/cameradirect.jd index 03ad119..4b6f0d2 100644 --- a/docs/html/training/camera/cameradirect.jd +++ b/docs/html/training/camera/cameradirect.jd @@ -35,7 +35,7 @@ previous.link=videobasics.html the framework APIs.</p> <p>Directly controlling a device camera requires a lot more code than requesting pictures or videos -from existing camera applications. However, if you want to build a specialized camera application or +from existing camera applications. However, if you want to build a specialized camera application or something fully integrated in your app UI, this lesson shows you how.</p> @@ -95,7 +95,7 @@ camera sensor is picking up.</p> <p>To get started with displaying a preview, you need preview class. The preview requires an implementation of the {@code android.view.SurfaceHolder.Callback} interface, which is used to pass image -data from the camera hardware the application.</p> +data from the camera hardware to the application.</p> <pre> class Preview extends ViewGroup implements SurfaceHolder.Callback { @@ -214,7 +214,7 @@ takePicture()}.</p> <h2 id="TaskRestartPreview">Restart the Preview</h2> -<p>After a picture is taken, you must to restart the preview before the user +<p>After a picture is taken, you must restart the preview before the user can take another picture. In this example, the restart is done by overloading the shutter button.</p> diff --git a/docs/html/training/camera/photobasics.jd b/docs/html/training/camera/photobasics.jd index e6ab43e..3420918 100644 --- a/docs/html/training/camera/photobasics.jd +++ b/docs/html/training/camera/photobasics.jd @@ -55,7 +55,7 @@ for you.</p> <h2 id="TaskManifest">Request Camera Permission</h2> <p>If an essential function of your application is taking pictures, then restrict -its visibility in Android Market to devices that have a camera. To advertise +its visibility on Google Play to devices that have a camera. To advertise that your application depends on having a camera, put a <a href="{@docRoot}guide/topics/manifest/uses-feature-element.html"> {@code <uses-feature>}</a> tag in your manifest file:</p> @@ -68,7 +68,7 @@ href="{@docRoot}guide/topics/manifest/uses-feature-element.html"> {@code </pre> <p>If your application uses, but does not require a camera in order to function, add {@code -android:required="false"} to the tag. In doing so, Android Market will allow devices without a +android:required="false"} to the tag. In doing so, Google Play will allow devices without a camera to download your application. It's then your responsibility to check for the availability of the camera at runtime by calling {@link android.content.pm.PackageManager#hasSystemFeature hasSystemFeature(PackageManager.FEATURE_CAMERA)}. diff --git a/docs/html/training/camera/videobasics.jd b/docs/html/training/camera/videobasics.jd index a3512b0..5fe1a3a 100644 --- a/docs/html/training/camera/videobasics.jd +++ b/docs/html/training/camera/videobasics.jd @@ -62,7 +62,7 @@ records video. In this lesson, you make it do this for you.</p> </pre> <p>If your application uses, but does not require a camera in order to function, add {@code -android:required="false"} to the tag. In doing so, Android Market will allow devices without a +android:required="false"} to the tag. In doing so, Google Play will allow devices without a camera to download your application. It's then your responsibility to check for the availability of the camera at runtime by calling {@link android.content.pm.PackageManager#hasSystemFeature hasSystemFeature(PackageManager.FEATURE_CAMERA)}. @@ -107,7 +107,7 @@ public static boolean isIntentAvailable(Context context, String action) { <p>The Android Camera application returns the video in the {@link android.content.Intent} delivered to {@link android.app.Activity#onActivityResult onActivityResult()} as a {@link android.net.Uri} pointing to the video location in storage. The following code -retrieves this image and displays it in a {@link android.widget.VideoView}.</p> +retrieves this video and displays it in a {@link android.widget.VideoView}.</p> <pre> private void handleCameraVideo(Intent intent) { diff --git a/docs/html/training/displaying-bitmaps/cache-bitmap.jd b/docs/html/training/displaying-bitmaps/cache-bitmap.jd new file mode 100644 index 0000000..94abe21 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/cache-bitmap.jd @@ -0,0 +1,337 @@ +page.title=Caching Bitmaps +parent.title=Displaying Bitmaps Efficiently +parent.link=index.html + +trainingnavtop=true +next.title=Displaying Bitmaps in Your UI +next.link=display-bitmap.html +previous.title=Processing Bitmaps Off the UI Thread +previous.link=process-bitmap.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#memory-cache">Use a Memory Cache</a></li> + <li><a href="#disk-cache">Use a Disk Cache</a></li> + <li><a href="#config-changes">Handle Configuration Changes</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="{@docRoot}shareables/training/BitmapFun.zip" class="button">Download the sample</a> + <p class="filename">BitmapFun.zip</p> +</div> + +</div> +</div> + +<p>Loading a single bitmap into your user interface (UI) is straightforward, however things get more +complicated if you need to load a larger set of images at once. In many cases (such as with +components like {@link android.widget.ListView}, {@link android.widget.GridView} or {@link +android.support.v4.view.ViewPager }), the total number of images on-screen combined with images that +might soon scroll onto the screen are essentially unlimited.</p> + +<p>Memory usage is kept down with components like this by recycling the child views as they move +off-screen. The garbage collector also frees up your loaded bitmaps, assuming you don't keep any +long lived references. This is all good and well, but in order to keep a fluid and fast-loading UI +you want to avoid continually processing these images each time they come back on-screen. A memory +and disk cache can often help here, allowing components to quickly reload processed images.</p> + +<p>This lesson walks you through using a memory and disk bitmap cache to improve the responsiveness +and fluidity of your UI when loading multiple bitmaps.</p> + +<h2 id="memory-cache">Use a Memory Cache</h2> + +<p>A memory cache offers fast access to bitmaps at the cost of taking up valuable application +memory. The {@link android.util.LruCache} class (also available in the <a +href="{@docRoot}reference/android/support/v4/util/LruCache.html">Support Library</a> for use back +to API Level 4) is particularly well suited to the task of caching bitmaps, keeping recently +referenced objects in a strong referenced {@link java.util.LinkedHashMap} and evicting the least +recently used member before the cache exceeds its designated size.</p> + +<p class="note"><strong>Note:</strong> In the past, a popular memory cache implementation was a +{@link java.lang.ref.SoftReference} or {@link java.lang.ref.WeakReference} bitmap cache, however +this is not recommended. Starting from Android 2.3 (API Level 9) the garbage collector is more +aggressive with collecting soft/weak references which makes them fairly ineffective. In addition, +prior to Android 3.0 (API Level 11), the backing data of a bitmap was stored in native memory which +is not released in a predictable manner, potentially causing an application to briefly exceed its +memory limits and crash.</p> + +<p>In order to choose a suitable size for a {@link android.util.LruCache}, a number of factors +should be taken into consideration, for example:</p> + +<ul> + <li>How memory intensive is the rest of your activity and/or application?</li> + <li>How many images will be on-screen at once? How many need to be available ready to come + on-screen?</li> + <li>What is the screen size and density of the device? An extra high density screen (xhdpi) device + like <a href="http://www.android.com/devices/detail/galaxy-nexus">Galaxy Nexus</a> will need a + larger cache to hold the same number of images in memory compared to a device like <a + href="http://www.android.com/devices/detail/nexus-s">Nexus S</a> (hdpi).</li> + <li>What dimensions and configuration are the bitmaps and therefore how much memory will each take + up?</li> + <li>How frequently will the images be accessed? Will some be accessed more frequently than others? + If so, perhaps you may want to keep certain items always in memory or even have multiple {@link + android.util.LruCache} objects for different groups of bitmaps.</li> + <li>Can you balance quality against quantity? Sometimes it can be more useful to store a larger + number of lower quality bitmaps, potentially loading a higher quality version in another + background task.</li> +</ul> + +<p>There is no specific size or formula that suits all applications, it's up to you to analyze your +usage and come up with a suitable solution. A cache that is too small causes additional overhead with +no benefit, a cache that is too large can once again cause {@code java.lang.OutOfMemory} exceptions +and leave the rest of your app little memory to work with.</p> + +<p>Here’s an example of setting up a {@link android.util.LruCache} for bitmaps:</p> + +<pre> +private LruCache<String, Bitmap> mMemoryCache; + +@Override +protected void onCreate(Bundle savedInstanceState) { + ... + // Get memory class of this device, exceeding this amount will throw an + // OutOfMemory exception. + final int memClass = ((ActivityManager) context.getSystemService( + Context.ACTIVITY_SERVICE)).getMemoryClass(); + + // Use 1/8th of the available memory for this memory cache. + final int cacheSize = 1024 * 1024 * memClass / 8; + + mMemoryCache = new LruCache<String, Bitmap>(cacheSize) { + @Override + protected int sizeOf(String key, Bitmap bitmap) { + // The cache size will be measured in bytes rather than number of items. + return bitmap.getByteCount(); + } + }; + ... +} + +public void addBitmapToMemoryCache(String key, Bitmap bitmap) { + if (getBitmapFromMemCache(key) == null) { + mMemoryCache.put(key, bitmap); + } +} + +public Bitmap getBitmapFromMemCache(String key) { + return mMemoryCache.get(key); +} +</pre> + +<p class="note"><strong>Note:</strong> In this example, one eighth of the application memory is +allocated for our cache. On a normal/hdpi device this is a minimum of around 4MB (32/8). A full +screen {@link android.widget.GridView} filled with images on a device with 800x480 resolution would +use around 1.5MB (800*480*4 bytes), so this would cache a minimum of around 2.5 pages of images in +memory.</p> + +<p>When loading a bitmap into an {@link android.widget.ImageView}, the {@link android.util.LruCache} +is checked first. If an entry is found, it is used immediately to update the {@link +android.widget.ImageView}, otherwise a background thread is spawned to process the image:</p> + +<pre> +public void loadBitmap(int resId, ImageView imageView) { + final String imageKey = String.valueOf(resId); + + final Bitmap bitmap = getBitmapFromMemCache(imageKey); + if (bitmap != null) { + mImageView.setImageBitmap(bitmap); + } else { + mImageView.setImageResource(R.drawable.image_placeholder); + BitmapWorkerTask task = new BitmapWorkerTask(mImageView); + task.execute(resId); + } +} +</pre> + +<p>The <a href="process-bitmap.html#BitmapWorkerTask">{@code BitmapWorkerTask}</a> also needs to be +updated to add entries to the memory cache:</p> + +<pre> +class BitmapWorkerTask extends AsyncTask<Integer, Void, Bitmap> { + ... + // Decode image in background. + @Override + protected Bitmap doInBackground(Integer... params) { + final Bitmap bitmap = decodeSampledBitmapFromResource( + getResources(), params[0], 100, 100)); + addBitmapToMemoryCache(String.valueOf(params[0]), bitmap); + return bitmap; + } + ... +} +</pre> + +<h2 id="disk-cache">Use a Disk Cache</h2> + +<p>A memory cache is useful in speeding up access to recently viewed bitmaps, however you cannot +rely on images being available in this cache. Components like {@link android.widget.GridView} with +larger datasets can easily fill up a memory cache. Your application could be interrupted by another +task like a phone call, and while in the background it might be killed and the memory cache +destroyed. Once the user resumes, your application it has to process each image again.</p> + +<p>A disk cache can be used in these cases to persist processed bitmaps and help decrease loading +times where images are no longer available in a memory cache. Of course, fetching images from disk +is slower than loading from memory and should be done in a background thread, as disk read times can +be unpredictable.</p> + +<p class="note"><strong>Note:</strong> A {@link android.content.ContentProvider} might be a more +appropriate place to store cached images if they are accessed more frequently, for example in an +image gallery application.</p> + +<p>Included in the sample code of this class is a basic {@code DiskLruCache} implementation. +However, a more robust and recommended {@code DiskLruCache} solution is included in the Android 4.0 +source code ({@code libcore/luni/src/main/java/libcore/io/DiskLruCache.java}). Back-porting this +class for use on previous Android releases should be fairly straightforward (a <a +href="http://www.google.com/search?q=disklrucache">quick search</a> shows others who have already +implemented this solution).</p> + +<p>Here’s updated example code that uses the simple {@code DiskLruCache} included in the sample +application of this class:</p> + +<pre> +private DiskLruCache mDiskCache; +private static final int DISK_CACHE_SIZE = 1024 * 1024 * 10; // 10MB +private static final String DISK_CACHE_SUBDIR = "thumbnails"; + +@Override +protected void onCreate(Bundle savedInstanceState) { + ... + // Initialize memory cache + ... + File cacheDir = getCacheDir(this, DISK_CACHE_SUBDIR); + mDiskCache = DiskLruCache.openCache(this, cacheDir, DISK_CACHE_SIZE); + ... +} + +class BitmapWorkerTask extends AsyncTask<Integer, Void, Bitmap> { + ... + // Decode image in background. + @Override + protected Bitmap doInBackground(Integer... params) { + final String imageKey = String.valueOf(params[0]); + + // Check disk cache in background thread + Bitmap bitmap = getBitmapFromDiskCache(imageKey); + + if (bitmap == null) { // Not found in disk cache + // Process as normal + final Bitmap bitmap = decodeSampledBitmapFromResource( + getResources(), params[0], 100, 100)); + } + + // Add final bitmap to caches + addBitmapToCache(String.valueOf(imageKey, bitmap); + + return bitmap; + } + ... +} + +public void addBitmapToCache(String key, Bitmap bitmap) { + // Add to memory cache as before + if (getBitmapFromMemCache(key) == null) { + mMemoryCache.put(key, bitmap); + } + + // Also add to disk cache + if (!mDiskCache.containsKey(key)) { + mDiskCache.put(key, bitmap); + } +} + +public Bitmap getBitmapFromDiskCache(String key) { + return mDiskCache.get(key); +} + +// Creates a unique subdirectory of the designated app cache directory. Tries to use external +// but if not mounted, falls back on internal storage. +public static File getCacheDir(Context context, String uniqueName) { + // Check if media is mounted or storage is built-in, if so, try and use external cache dir + // otherwise use internal cache dir + final String cachePath = Environment.getExternalStorageState() == Environment.MEDIA_MOUNTED + || !Environment.isExternalStorageRemovable() ? + context.getExternalCacheDir().getPath() : context.getCacheDir().getPath(); + + return new File(cachePath + File.separator + uniqueName); +} +</pre> + +<p>While the memory cache is checked in the UI thread, the disk cache is checked in the background +thread. Disk operations should never take place on the UI thread. When image processing is +complete, the final bitmap is added to both the memory and disk cache for future use.</p> + +<h2 id="config-changes">Handle Configuration Changes</h2> + +<p>Runtime configuration changes, such as a screen orientation change, cause Android to destroy and +restart the running activity with the new configuration (For more information about this behavior, +see <a href="{@docRoot}guide/topics/resources/runtime-changes.html">Handling Runtime Changes</a>). +You want to avoid having to process all your images again so the user has a smooth and fast +experience when a configuration change occurs.</p> + +<p>Luckily, you have a nice memory cache of bitmaps that you built in the <a +href="#memory-cache">Use a Memory Cache</a> section. This cache can be passed through to the new +activity instance using a {@link android.app.Fragment} which is preserved by calling {@link +android.app.Fragment#setRetainInstance setRetainInstance(true)}). After the activity has been +recreated, this retained {@link android.app.Fragment} is reattached and you gain access to the +existing cache object, allowing images to be quickly fetched and re-populated into the {@link +android.widget.ImageView} objects.</p> + +<p>Here’s an example of retaining a {@link android.util.LruCache} object across configuration +changes using a {@link android.app.Fragment}:</p> + +<pre> +private LruCache<String, Bitmap> mMemoryCache; + +@Override +protected void onCreate(Bundle savedInstanceState) { + ... + RetainFragment mRetainFragment = + RetainFragment.findOrCreateRetainFragment(getFragmentManager()); + mMemoryCache = RetainFragment.mRetainedCache; + if (mMemoryCache == null) { + mMemoryCache = new LruCache<String, Bitmap>(cacheSize) { + ... // Initialize cache here as usual + } + mRetainFragment.mRetainedCache = mMemoryCache; + } + ... +} + +class RetainFragment extends Fragment { + private static final String TAG = "RetainFragment"; + public LruCache<String, Bitmap> mRetainedCache; + + public RetainFragment() {} + + public static RetainFragment findOrCreateRetainFragment(FragmentManager fm) { + RetainFragment fragment = (RetainFragment) fm.findFragmentByTag(TAG); + if (fragment == null) { + fragment = new RetainFragment(); + } + return fragment; + } + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + <strong>setRetainInstance(true);</strong> + } +} +</pre> + +<p>To test this out, try rotating a device both with and without retaining the {@link +android.app.Fragment}. You should notice little to no lag as the images populate the activity almost +instantly from memory when you retain the cache. Any images not found in the memory cache are +hopefully available in the disk cache, if not, they are processed as usual.</p> diff --git a/docs/html/training/displaying-bitmaps/display-bitmap.jd b/docs/html/training/displaying-bitmaps/display-bitmap.jd new file mode 100644 index 0000000..7a93313 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/display-bitmap.jd @@ -0,0 +1,400 @@ +page.title=Displaying Bitmaps in Your UI +parent.title=Displaying Bitmaps Efficiently +parent.link=index.html + +trainingnavtop=true +previous.title=Caching Bitmaps +previous.link=cache-bitmap.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#viewpager">Load Bitmaps into a ViewPager Implementation</a></li> + <li><a href="#gridview">Load Bitmaps into a GridView Implementation</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}design/patterns/swipe-views.html">Android Design: Swipe Views</a></li> + <li><a href="{@docRoot}design/building-blocks/grid-lists.html">Android Design: Grid Lists</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="{@docRoot}shareables/training/BitmapFun.zip" class="button">Download the sample</a> + <p class="filename">BitmapFun.zip</p> +</div> + +</div> +</div> + +<p></p> + +<p>This lesson brings together everything from previous lessons, showing you how to load multiple +bitmaps into {@link android.support.v4.view.ViewPager} and {@link android.widget.GridView} +components using a background thread and bitmap cache, while dealing with concurrency and +configuration changes.</p> + +<h2 id="viewpager">Load Bitmaps into a ViewPager Implementation</h2> + +<p>The <a href="{@docRoot}design/patterns/swipe-views.html">swipe view pattern</a> is an excellent +way to navigate the detail view of an image gallery. You can implement this pattern using a {@link +android.support.v4.view.ViewPager} component backed by a {@link +android.support.v4.view.PagerAdapter}. However, a more suitable backing adapter is the subclass +{@link android.support.v4.app.FragmentStatePagerAdapter} which automatically destroys and saves +state of the {@link android.app.Fragment Fragments} in the {@link android.support.v4.view.ViewPager} +as they disappear off-screen, keeping memory usage down.</p> + +<p class="note"><strong>Note:</strong> If you have a smaller number of images and are confident they +all fit within the application memory limit, then using a regular {@link +android.support.v4.view.PagerAdapter} or {@link android.support.v4.app.FragmentPagerAdapter} might +be more appropriate.</p> + +<p>Here’s an implementation of a {@link android.support.v4.view.ViewPager} with {@link +android.widget.ImageView} children. The main activity holds the {@link +android.support.v4.view.ViewPager} and the adapter:</p> + +<pre> +public class ImageDetailActivity extends FragmentActivity { + public static final String EXTRA_IMAGE = "extra_image"; + + private ImagePagerAdapter mAdapter; + private ViewPager mPager; + + // A static dataset to back the ViewPager adapter + public final static Integer[] imageResIds = new Integer[] { + R.drawable.sample_image_1, R.drawable.sample_image_2, R.drawable.sample_image_3, + R.drawable.sample_image_4, R.drawable.sample_image_5, R.drawable.sample_image_6, + R.drawable.sample_image_7, R.drawable.sample_image_8, R.drawable.sample_image_9}; + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + setContentView(R.layout.image_detail_pager); // Contains just a ViewPager + + mAdapter = new ImagePagerAdapter(getSupportFragmentManager(), imageResIds.length); + mPager = (ViewPager) findViewById(R.id.pager); + mPager.setAdapter(mAdapter); + } + + public static class ImagePagerAdapter extends FragmentStatePagerAdapter { + private final int mSize; + + public ImagePagerAdapter(FragmentManager fm, int size) { + super(fm); + mSize = size; + } + + @Override + public int getCount() { + return mSize; + } + + @Override + public Fragment getItem(int position) { + return ImageDetailFragment.newInstance(position); + } + } +} +</pre> + +<p>The details {@link android.app.Fragment} holds the {@link android.widget.ImageView} children:</p> + +<pre> +public class ImageDetailFragment extends Fragment { + private static final String IMAGE_DATA_EXTRA = "resId"; + private int mImageNum; + private ImageView mImageView; + + static ImageDetailFragment newInstance(int imageNum) { + final ImageDetailFragment f = new ImageDetailFragment(); + final Bundle args = new Bundle(); + args.putInt(IMAGE_DATA_EXTRA, imageNum); + f.setArguments(args); + return f; + } + + // Empty constructor, required as per Fragment docs + public ImageDetailFragment() {} + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + mImageNum = getArguments() != null ? getArguments().getInt(IMAGE_DATA_EXTRA) : -1; + } + + @Override + public View onCreateView(LayoutInflater inflater, ViewGroup container, + Bundle savedInstanceState) { + // image_detail_fragment.xml contains just an ImageView + final View v = inflater.inflate(R.layout.image_detail_fragment, container, false); + mImageView = (ImageView) v.findViewById(R.id.imageView); + return v; + } + + @Override + public void onActivityCreated(Bundle savedInstanceState) { + super.onActivityCreated(savedInstanceState); + final int resId = ImageDetailActivity.imageResIds[mImageNum]; + <strong>mImageView.setImageResource(resId);</strong> // Load image into ImageView + } +} +</pre> + +<p>Hopefully you noticed the issue with this implementation; The images are being read from +resources on the UI thread which can lead to an application hanging and being force closed. Using an +{@link android.os.AsyncTask} as described in the <a href="process-bitmap.html">Processing Bitmaps Off +the UI Thread</a> lesson, it’s straightforward to move image loading and processing to a background +thread:</p> + +<pre> +public class ImageDetailActivity extends FragmentActivity { + ... + + public void loadBitmap(int resId, ImageView imageView) { + mImageView.setImageResource(R.drawable.image_placeholder); + BitmapWorkerTask task = new BitmapWorkerTask(mImageView); + task.execute(resId); + } + + ... // include <a href="process-bitmap.html#BitmapWorkerTask">{@code BitmapWorkerTask}</a> class +} + +public class ImageDetailFragment extends Fragment { + ... + + @Override + public void onActivityCreated(Bundle savedInstanceState) { + super.onActivityCreated(savedInstanceState); + if (ImageDetailActivity.class.isInstance(getActivity())) { + final int resId = ImageDetailActivity.imageResIds[mImageNum]; + // Call out to ImageDetailActivity to load the bitmap in a background thread + ((ImageDetailActivity) getActivity()).loadBitmap(resId, mImageView); + } + } +} +</pre> + +<p>Any additional processing (such as resizing or fetching images from the network) can take place +in the <a href="process-bitmap.html#BitmapWorkerTask">{@code BitmapWorkerTask}</a> without affecting +responsiveness of the main UI. If the background thread is doing more than just loading an image +directly from disk, it can also be beneficial to add a memory and/or disk cache as described in the +lesson <a href="cache-bitmap.html#memory-cache">Caching Bitmaps</a>. Here's the additional +modifications for a memory cache:</p> + +<pre> +public class ImageDetailActivity extends FragmentActivity { + ... + private LruCache<String, Bitmap> mMemoryCache; + + @Override + public void onCreate(Bundle savedInstanceState) { + ... + // initialize LruCache as per <a href="cache-bitmap.html#memory-cache">Use a Memory Cache</a> section + } + + public void loadBitmap(int resId, ImageView imageView) { + final String imageKey = String.valueOf(resId); + + final Bitmap bitmap = mMemoryCache.get(imageKey); + if (bitmap != null) { + mImageView.setImageBitmap(bitmap); + } else { + mImageView.setImageResource(R.drawable.image_placeholder); + BitmapWorkerTask task = new BitmapWorkerTask(mImageView); + task.execute(resId); + } + } + + ... // include updated BitmapWorkerTask from <a href="cache-bitmap.html#memory-cache">Use a Memory Cache</a> section +} +</pre> + +<p>Putting all these pieces together gives you a responsive {@link +android.support.v4.view.ViewPager} implementation with minimal image loading latency and the ability +to do as much or as little background processing on your images as needed.</p> + +<h2 id="gridview">Load Bitmaps into a GridView Implementation</h2> + +<p>The <a href="{@docRoot}design/building-blocks/grid-lists.html">grid list building block</a> is +useful for showing image data sets and can be implemented using a {@link android.widget.GridView} +component in which many images can be on-screen at any one time and many more need to be ready to +appear if the user scrolls up or down. When implementing this type of control, you must ensure the +UI remains fluid, memory usage remains under control and concurrency is handled correctly (due to +the way {@link android.widget.GridView} recycles its children views).</p> + +<p>To start with, here is a standard {@link android.widget.GridView} implementation with {@link +android.widget.ImageView} children placed inside a {@link android.app.Fragment}:</p> + +<pre> +public class ImageGridFragment extends Fragment implements AdapterView.OnItemClickListener { + private ImageAdapter mAdapter; + + // A static dataset to back the GridView adapter + public final static Integer[] imageResIds = new Integer[] { + R.drawable.sample_image_1, R.drawable.sample_image_2, R.drawable.sample_image_3, + R.drawable.sample_image_4, R.drawable.sample_image_5, R.drawable.sample_image_6, + R.drawable.sample_image_7, R.drawable.sample_image_8, R.drawable.sample_image_9}; + + // Empty constructor as per Fragment docs + public ImageGridFragment() {} + + @Override + public void onCreate(Bundle savedInstanceState) { + super.onCreate(savedInstanceState); + mAdapter = new ImageAdapter(getActivity()); + } + + @Override + public View onCreateView( + LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) { + final View v = inflater.inflate(R.layout.image_grid_fragment, container, false); + final GridView mGridView = (GridView) v.findViewById(R.id.gridView); + mGridView.setAdapter(mAdapter); + mGridView.setOnItemClickListener(this); + return v; + } + + @Override + public void onItemClick(AdapterView<?> parent, View v, int position, long id) { + final Intent i = new Intent(getActivity(), ImageDetailActivity.class); + i.putExtra(ImageDetailActivity.EXTRA_IMAGE, position); + startActivity(i); + } + + private class ImageAdapter extends BaseAdapter { + private final Context mContext; + + public ImageAdapter(Context context) { + super(); + mContext = context; + } + + @Override + public int getCount() { + return imageResIds.length; + } + + @Override + public Object getItem(int position) { + return imageResIds[position]; + } + + @Override + public long getItemId(int position) { + return position; + } + + @Override + public View getView(int position, View convertView, ViewGroup container) { + ImageView imageView; + if (convertView == null) { // if it's not recycled, initialize some attributes + imageView = new ImageView(mContext); + imageView.setScaleType(ImageView.ScaleType.CENTER_CROP); + imageView.setLayoutParams(new GridView.LayoutParams( + LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)); + } else { + imageView = (ImageView) convertView; + } + <strong>imageView.setImageResource(imageResIds[position]);</strong> // Load image into ImageView + return imageView; + } + } +} +</pre> + +<p>Once again, the problem with this implementation is that the image is being set in the UI thread. +While this may work for small, simple images (due to system resource loading and caching), if any +additional processing needs to be done, your UI grinds to a halt.</p> + +<p>The same asynchronous processing and caching methods from the previous section can be implemented +here. However, you also need to wary of concurrency issues as the {@link android.widget.GridView} +recycles its children views. To handle this, use the techniques discussed in the <a +href="process-bitmap#concurrency">Processing Bitmaps Off the UI Thread</a> lesson. Here is the updated +solution:</p> + +<pre> +public class ImageGridFragment extends Fragment implements AdapterView.OnItemClickListener { + ... + + private class ImageAdapter extends BaseAdapter { + ... + + @Override + public View getView(int position, View convertView, ViewGroup container) { + ... + <strong>loadBitmap(imageResIds[position], imageView)</strong> + return imageView; + } + } + + public void loadBitmap(int resId, ImageView imageView) { + if (cancelPotentialWork(resId, imageView)) { + final BitmapWorkerTask task = new BitmapWorkerTask(imageView); + final AsyncDrawable asyncDrawable = + new AsyncDrawable(getResources(), mPlaceHolderBitmap, task); + imageView.setImageDrawable(asyncDrawable); + task.execute(resId); + } + } + + static class AsyncDrawable extends BitmapDrawable { + private final WeakReference<BitmapWorkerTask> bitmapWorkerTaskReference; + + public AsyncDrawable(Resources res, Bitmap bitmap, + BitmapWorkerTask bitmapWorkerTask) { + super(res, bitmap); + bitmapWorkerTaskReference = + new WeakReference<BitmapWorkerTask>(bitmapWorkerTask); + } + + public BitmapWorkerTask getBitmapWorkerTask() { + return bitmapWorkerTaskReference.get(); + } + } + + public static boolean cancelPotentialWork(int data, ImageView imageView) { + final BitmapWorkerTask bitmapWorkerTask = getBitmapWorkerTask(imageView); + + if (bitmapWorkerTask != null) { + final int bitmapData = bitmapWorkerTask.data; + if (bitmapData != data) { + // Cancel previous task + bitmapWorkerTask.cancel(true); + } else { + // The same work is already in progress + return false; + } + } + // No task associated with the ImageView, or an existing task was cancelled + return true; + } + + private static BitmapWorkerTask getBitmapWorkerTask(ImageView imageView) { + if (imageView != null) { + final Drawable drawable = imageView.getDrawable(); + if (drawable instanceof AsyncDrawable) { + final AsyncDrawable asyncDrawable = (AsyncDrawable) drawable; + return asyncDrawable.getBitmapWorkerTask(); + } + } + return null; + } + + ... // include updated <a href="process-bitmap.html#BitmapWorkerTaskUpdated">{@code BitmapWorkerTask}</a> class +</pre> + +<p class="note"><strong>Note:</strong> The same code can easily be adapted to work with {@link +android.widget.ListView} as well.</p> + +<p>This implementation allows for flexibility in how the images are processed and loaded without +impeding the smoothness of the UI. In the background task you can load images from the network or +resize large digital camera photos and the images appear as the tasks finish processing.</p> + +<p>For a full example of this and other concepts discussed in this lesson, please see the included +sample application.</p> diff --git a/docs/html/training/displaying-bitmaps/index.jd b/docs/html/training/displaying-bitmaps/index.jd new file mode 100644 index 0000000..6755c24 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/index.jd @@ -0,0 +1,78 @@ +page.title=Displaying Bitmaps Efficiently + +trainingnavtop=true +startpage=true +next.title=Loading Large Bitmaps Efficiently +next.link=load-bitmap.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 2.1 (API Level 7) or higher</li> + <li><a href="{@docRoot}sdk/compatibility-library.html">Support Library</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="{@docRoot}shareables/training/BitmapFun.zip" class="button">Download the sample</a> + <p class="filename">BitmapFun.zip</p> +</div> + +</div> +</div> + +<p>This class covers some common techniques for processing and loading {@link +android.graphics.Bitmap} objects in a way that keeps your user interface (UI) components responsive +and avoids exceeding your application memory limit. If you're not careful, bitmaps can quickly +consume your available memory budget leading to an application crash due to the dreaded +exception:<br />{@code java.lang.OutofMemoryError: bitmap size exceeds VM budget}.</p> + +<p>There are a number of reasons why loading bitmaps in your Android application is tricky:</p> + +<ul> + <li>Mobile devices typically have constrained system resources. Android devices can have as little + as 16MB of memory available to a single application. The <a + href="http://source.android.com/compatibility/downloads.html">Android Compatibility Definition + Document</a> (CDD), <i>Section 3.7. Virtual Machine Compatibility</i> gives the required minimum + application memory for various screen sizes and densities. Applications should be optimized to + perform under this minimum memory limit. However, keep in mind many devices are configured with + higher limits.</li> + <li>Bitmaps take up a lot of memory, especially for rich images like photographs. For example, the + camera on the <a href="http://www.google.com/nexus/">Galaxy Nexus</a> takes photos up to 2592x1936 + pixels (5 megapixels). If the bitmap configuration used is {@link + android.graphics.Bitmap.Config ARGB_8888} (the default from the Android 2.3 onward) then loading + this image into memory takes about 19MB of memory (2592*1936*4 bytes), immediately exhausting the + per-app limit on some devices.</li> + <li>Android app UI’s frequently require several bitmaps to be loaded at once. Components such as + {@link android.widget.ListView}, {@link android.widget.GridView} and {@link + android.support.v4.view.ViewPager} commonly include multiple bitmaps on-screen at once with many + more potentially off-screen ready to show at the flick of a finger.</li> +</ul> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="load-bitmap.html">Loading Large Bitmaps Efficiently</a></b></dt> + <dd>This lesson walks you through decoding large bitmaps without exceeding the per application + memory limit.</dd> + + <dt><b><a href="process-bitmap.html">Processing Bitmaps Off the UI Thread</a></b></dt> + <dd>Bitmap processing (resizing, downloading from a remote source, etc.) should never take place + on the main UI thread. This lesson walks you through processing bitmaps in a background thread + using {@link android.os.AsyncTask} and explains how to handle concurrency issues.</dd> + + <dt><b><a href="cache-bitmap.html">Caching Bitmaps</a></b></dt> + <dd>This lesson walks you through using a memory and disk bitmap cache to improve the + responsiveness and fluidity of your UI when loading multiple bitmaps.</dd> + + <dt><b><a href="display-bitmap.html">Displaying Bitmaps in Your UI</a></b></dt> + <dd>This lesson brings everything together, showing you how to load multiple bitmaps into + components like {@link android.support.v4.view.ViewPager} and {@link android.widget.GridView} + using a background thread and bitmap cache.</dd> + +</dl>
\ No newline at end of file diff --git a/docs/html/training/displaying-bitmaps/load-bitmap.jd b/docs/html/training/displaying-bitmaps/load-bitmap.jd new file mode 100644 index 0000000..c0a5709 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/load-bitmap.jd @@ -0,0 +1,165 @@ +page.title=Loading Large Bitmaps Efficiently +parent.title=Displaying Bitmaps Efficiently +parent.link=index.html + +trainingnavtop=true +next.title=Processing Bitmaps Off the UI Thread +next.link=process-bitmap.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#read-bitmap">Read Bitmap Dimensions and Type</a></li> + <li><a href="#load-bitmap">Load a Scaled Down Version into Memory</a></li> +</ol> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="{@docRoot}shareables/training/BitmapFun.zip" class="button">Download the sample</a> + <p class="filename">BitmapFun.zip</p> +</div> + +</div> +</div> + +<p>Images come in all shapes and sizes. In many cases they are larger than required for a typical +application user interface (UI). For example, the system Gallery application displays photos taken +using your Android devices's camera which are typically much higher resolution than the screen +density of your device.</p> + +<p>Given that you are working with limited memory, ideally you only want to load a lower resolution +version in memory. The lower resolution version should match the size of the UI component that +displays it. An image with a higher resolution does not provide any visible benefit, but still takes +up precious memory and incurs additional performance overhead due to additional on the fly +scaling.</p> + +<p>This lesson walks you through decoding large bitmaps without exceeding the per application +memory limit by loading a smaller subsampled version in memory.</p> + +<h2 id="read-bitmap">Read Bitmap Dimensions and Type</h2> + +<p>The {@link android.graphics.BitmapFactory} class provides several decoding methods ({@link +android.graphics.BitmapFactory#decodeByteArray(byte[],int,int,android.graphics.BitmapFactory.Options) +decodeByteArray()}, {@link +android.graphics.BitmapFactory#decodeFile(java.lang.String,android.graphics.BitmapFactory.Options) +decodeFile()}, {@link +android.graphics.BitmapFactory#decodeResource(android.content.res.Resources,int,android.graphics.BitmapFactory.Options) +decodeResource()}, etc.) for creating a {@link android.graphics.Bitmap} from various sources. Choose +the most appropriate decode method based on your image data source. These methods attempt to +allocate memory for the constructed bitmap and therefore can easily result in an {@code OutOfMemory} +exception. Each type of decode method has additional signatures that let you specify decoding +options via the {@link android.graphics.BitmapFactory.Options} class. Setting the {@link +android.graphics.BitmapFactory.Options#inJustDecodeBounds} property to {@code true} while decoding +avoids memory allocation, returning {@code null} for the bitmap object but setting {@link +android.graphics.BitmapFactory.Options#outWidth}, {@link +android.graphics.BitmapFactory.Options#outHeight} and {@link +android.graphics.BitmapFactory.Options#outMimeType}. This technique allows you to read the +dimensions and type of the image data prior to construction (and memory allocation) of the +bitmap.</p> + +<pre> +BitmapFactory.Options options = new BitmapFactory.Options(); +options.inJustDecodeBounds = true; +BitmapFactory.decodeResource(getResources(), R.id.myimage, options); +int imageHeight = options.outHeight; +int imageWidth = options.outWidth; +String imageType = options.outMimeType; +</pre> + +<p>To avoid {@code java.lang.OutOfMemory} exceptions, check the dimensions of a bitmap before +decoding it, unless you absolutely trust the source to provide you with predictably sized image data +that comfortably fits within the available memory.</p> + +<h2 id="load-bitmap">Load a Scaled Down Version into Memory</h2> + +<p>Now that the image dimensions are known, they can be used to decide if the full image should be +loaded into memory or if a subsampled version should be loaded instead. Here are some factors to +consider:</p> + +<ul> + <li>Estimated memory usage of loading the full image in memory.</li> + <li>Amount of memory you are willing to commit to loading this image given any other memory + requirements of your application.</li> + <li>Dimensions of the target {@link android.widget.ImageView} or UI component that the image + is to be loaded into.</li> + <li>Screen size and density of the current device.</li> +</ul> + +<p>For example, it’s not worth loading a 1024x768 pixel image into memory if it will eventually be +displayed in a 128x96 pixel thumbnail in an {@link android.widget.ImageView}.</p> + +<p>To tell the decoder to subsample the image, loading a smaller version into memory, set {@link +android.graphics.BitmapFactory.Options#inSampleSize} to {@code true} in your {@link +android.graphics.BitmapFactory.Options} object. For example, an image with resolution 2048x1536 that +is decoded with an {@link android.graphics.BitmapFactory.Options#inSampleSize} of 4 produces a +bitmap of approximately 512x384. Loading this into memory uses 0.75MB rather than 12MB for the full +image (assuming a bitmap configuration of {@link android.graphics.Bitmap.Config ARGB_8888}). Here’s +a method to calculate a the sample size value based on a target width and height:</p> + +<pre> +public static int calculateInSampleSize( + BitmapFactory.Options options, int reqWidth, int reqHeight) { + // Raw height and width of image + final int height = options.outHeight; + final int width = options.outWidth; + int inSampleSize = 1; + + if (height > reqHeight || width > reqWidth) { + if (width > height) { + inSampleSize = Math.round((float)height / (float)reqHeight); + } else { + inSampleSize = Math.round((float)width / (float)reqWidth); + } + } + return inSampleSize; +} +</pre> + +<p class="note"><strong>Note:</strong> Using powers of 2 for {@link +android.graphics.BitmapFactory.Options#inSampleSize} values is faster and more efficient for the +decoder. However, if you plan to cache the resized versions in memory or on disk, it’s usually still +worth decoding to the most appropriate image dimensions to save space.</p> + +<p>To use this method, first decode with {@link +android.graphics.BitmapFactory.Options#inJustDecodeBounds} set to {@code true}, pass the options +through and then decode again using the new {@link +android.graphics.BitmapFactory.Options#inSampleSize} value and {@link +android.graphics.BitmapFactory.Options#inJustDecodeBounds} set to {@code false}:</p> + +<a name="decodeSampledBitmapFromResource"></a> +<pre> +public static Bitmap decodeSampledBitmapFromResource(Resources res, int resId, + int reqWidth, int reqHeight) { + + // First decode with inJustDecodeBounds=true to check dimensions + final BitmapFactory.Options options = new BitmapFactory.Options(); + options.inJustDecodeBounds = true; + BitmapFactory.decodeResource(res, resId, options); + + // Calculate inSampleSize + options.inSampleSize = calculateInSampleSize(options, reqWidth, reqHeight); + + // Decode bitmap with inSampleSize set + options.inJustDecodeBounds = false; + return BitmapFactory.decodeResource(res, resId, options); +} +</pre> + +<p>This method makes it easy to load a bitmap of arbitrarily large size into an {@link +android.widget.ImageView} that displays a 100x100 pixel thumbnail, as shown in the following example +code:</p> + +<pre> +mImageView.setImageBitmap( + decodeSampledBitmapFromResource(getResources(), R.id.myimage, 100, 100)); +</pre> + +<p>You can follow a similar process to decode bitmaps from other sources, by substituting the +appropriate {@link +android.graphics.BitmapFactory#decodeByteArray(byte[],int,int,android.graphics.BitmapFactory.Options) +BitmapFactory.decode*} method as needed.</p>
\ No newline at end of file diff --git a/docs/html/training/displaying-bitmaps/process-bitmap.jd b/docs/html/training/displaying-bitmaps/process-bitmap.jd new file mode 100644 index 0000000..c1450b4 --- /dev/null +++ b/docs/html/training/displaying-bitmaps/process-bitmap.jd @@ -0,0 +1,239 @@ +page.title=Processing Bitmaps Off the UI Thread +parent.title=Displaying Bitmaps Efficiently +parent.link=index.html + +trainingnavtop=true +next.title=Caching Bitmaps +next.link=cache-bitmap.html +previous.title=Loading Large Bitmaps Efficiently +previous.link=load-bitmap.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#async-task">Use an AsyncTask</a></li> + <li><a href="#concurrency">Handle Concurrency</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/practices/design/responsiveness.html">Designing for Responsiveness</a></li> + <li><a + href="http://android-developers.blogspot.com/2010/07/multithreading-for-performance.html">Multithreading + for Performance</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> + <a href="{@docRoot}shareables/training/BitmapFun.zip" class="button">Download the sample</a> + <p class="filename">BitmapFun.zip</p> +</div> + +</div> +</div> + +<p>The {@link +android.graphics.BitmapFactory#decodeByteArray(byte[],int,int,android.graphics.BitmapFactory.Options) +BitmapFactory.decode*} methods, discussed in the <a href="load-bitmap.html">Load Large Bitmaps +Efficiently</a> lesson, should not be executed on the main UI thread if the source data is read from +disk or a network location (or really any source other than memory). The time this data takes to +load is unpredictable and depends on a variety of factors (speed of reading from disk or network, +size of image, power of CPU, etc.). If one of these tasks blocks the UI thread, the system flags +your application as non-responsive and the user has the option of closing it (see <a +href="{@docRoot}guide/practices/design/responsiveness.html">Designing for Responsiveness</a> for +more information).</p> + +<p>This lesson walks you through processing bitmaps in a background thread using +{@link android.os.AsyncTask} and shows you how to handle concurrency issues.</p> + +<h2 id="async-task">Use an AsyncTask</h2> + +<p>The {@link android.os.AsyncTask} class provides an easy way to execute some work in a background +thread and publish the results back on the UI thread. To use it, create a subclass and override the +provided methods. Here’s an example of loading a large image into an {@link +android.widget.ImageView} using {@link android.os.AsyncTask} and <a +href="load-bitmap.html#decodeSampledBitmapFromResource">{@code +decodeSampledBitmapFromResource()}</a>: </p> + +<a name="BitmapWorkerTask"></a> +<pre> +class BitmapWorkerTask extends AsyncTask<Integer, Void, Bitmap> { + private final WeakReference<ImageView> imageViewReference; + private int data = 0; + + public BitmapWorkerTask(ImageView imageView) { + // Use a WeakReference to ensure the ImageView can be garbage collected + imageViewReference = new WeakReference<ImageView>(imageView); + } + + // Decode image in background. + @Override + protected Bitmap doInBackground(Integer... params) { + data = params[0]; + return decodeSampledBitmapFromResource(getResources(), data, 100, 100)); + } + + // Once complete, see if ImageView is still around and set bitmap. + @Override + protected void onPostExecute(Bitmap bitmap) { + if (imageViewReference != null && bitmap != null) { + final ImageView imageView = imageViewReference.get(); + if (imageView != null) { + imageView.setImageBitmap(bitmap); + } + } + } +} +</pre> + +<p>The {@link java.lang.ref.WeakReference} to the {@link android.widget.ImageView} ensures that the +{@link android.os.AsyncTask} does not prevent the {@link android.widget.ImageView} and anything it +references from being garbage collected. There’s no guarantee the {@link android.widget.ImageView} +is still around when the task finishes, so you must also check the reference in {@link +android.os.AsyncTask#onPostExecute(Result) onPostExecute()}. The {@link android.widget.ImageView} +may no longer exist, if for example, the user navigates away from the activity or if a +configuration change happens before the task finishes.</p> + +<p>To start loading the bitmap asynchronously, simply create a new task and execute it:</p> + +<pre> +public void loadBitmap(int resId, ImageView imageView) { + BitmapWorkerTask task = new BitmapWorkerTask(imageView); + task.execute(resId); +} +</pre> + +<h2 id="concurrency">Handle Concurrency</h2> + +<p>Common view components such as {@link android.widget.ListView} and {@link +android.widget.GridView} introduce another issue when used in conjunction with the {@link +android.os.AsyncTask} as demonstrated in the previous section. In order to be efficient with memory, +these components recycle child views as the user scrolls. If each child view triggers an {@link +android.os.AsyncTask}, there is no guarantee that when it completes, the associated view has not +already been recycled for use in another child view. Furthermore, there is no guarantee that the +order in which asynchronous tasks are started is the order that they complete.</p> + +<p>The blog post <a +href="http://android-developers.blogspot.com/2010/07/multithreading-for-performance.html">Multithreading +for Performance</a> further discusses dealing with concurrency, and offers a solution where the +{@link android.widget.ImageView} stores a reference to the most recent {@link android.os.AsyncTask} +which can later be checked when the task completes. Using a similar method, the {@link +android.os.AsyncTask} from the previous section can be extended to follow a similar pattern.</p> + +<p>Create a dedicated {@link android.graphics.drawable.Drawable} subclass to store a reference +back to the worker task. In this case, a {@link android.graphics.drawable.BitmapDrawable} is used so +that a placeholder image can be displayed in the {@link android.widget.ImageView} while the task +completes:</p> + +<a name="AsyncDrawable"></a> +<pre> +static class AsyncDrawable extends BitmapDrawable { + private final WeakReference<BitmapWorkerTask> bitmapWorkerTaskReference; + + public AsyncDrawable(Resources res, Bitmap bitmap, + BitmapWorkerTask bitmapWorkerTask) { + super(res, bitmap); + bitmapWorkerTaskReference = + new WeakReference<BitmapWorkerTask>(bitmapWorkerTask); + } + + public BitmapWorkerTask getBitmapWorkerTask() { + return bitmapWorkerTaskReference.get(); + } +} +</pre> + +<p>Before executing the <a href="#BitmapWorkerTask">{@code BitmapWorkerTask}</a>, you create an <a +href="#AsyncDrawable">{@code AsyncDrawable}</a> and bind it to the target {@link +android.widget.ImageView}:</p> + +<pre> +public void loadBitmap(int resId, ImageView imageView) { + if (cancelPotentialWork(resId, imageView)) { + final BitmapWorkerTask task = new BitmapWorkerTask(imageView); + final AsyncDrawable asyncDrawable = + new AsyncDrawable(getResources(), mPlaceHolderBitmap, task); + imageView.setImageDrawable(asyncDrawable); + task.execute(resId); + } +} +</pre> + +<p>The {@code cancelPotentialWork} method referenced in the code sample above checks if another +running task is already associated with the {@link android.widget.ImageView}. If so, it attempts to +cancel the previous task by calling {@link android.os.AsyncTask#cancel cancel()}. In a small number +of cases, the new task data matches the existing task and nothing further needs to happen. Here is +the implementation of {@code cancelPotentialWork}:</p> + +<pre> +public static boolean cancelPotentialWork(int data, ImageView imageView) { + final BitmapWorkerTask bitmapWorkerTask = getBitmapWorkerTask(imageView); + + if (bitmapWorkerTask != null) { + final int bitmapData = bitmapWorkerTask.data; + if (bitmapData != data) { + // Cancel previous task + bitmapWorkerTask.cancel(true); + } else { + // The same work is already in progress + return false; + } + } + // No task associated with the ImageView, or an existing task was cancelled + return true; +} +</pre> + +<p>A helper method, {@code getBitmapWorkerTask()}, is used above to retrieve the task associated +with a particular {@link android.widget.ImageView}:</p> + +<pre> +private static BitmapWorkerTask getBitmapWorkerTask(ImageView imageView) { + if (imageView != null) { + final Drawable drawable = imageView.getDrawable(); + if (drawable instanceof AsyncDrawable) { + final AsyncDrawable asyncDrawable = (AsyncDrawable) drawable; + return asyncDrawable.getBitmapWorkerTask(); + } + } + return null; +} +</pre> + +<p>The last step is updating {@code onPostExecute()} in <a href="#BitmapWorkerTask">{@code +BitmapWorkerTask}</a> so that it checks if the task is cancelled and if the current task matches the +one associated with the {@link android.widget.ImageView}:</p> + +<a name="BitmapWorkerTaskUpdated"></a> +<pre> +class BitmapWorkerTask extends AsyncTask<Integer, Void, Bitmap> { + ... + + @Override + protected void onPostExecute(Bitmap bitmap) { + <strong>if (isCancelled()) { + bitmap = null; + }</strong> + + if (imageViewReference != null && bitmap != null) { + final ImageView imageView = imageViewReference.get(); + <strong>final BitmapWorkerTask bitmapWorkerTask = + getBitmapWorkerTask(imageView);</strong> + if (<strong>this == bitmapWorkerTask &&</strong> imageView != null) { + imageView.setImageBitmap(bitmap); + } + } + } +} +</pre> + +<p>This implementation is now suitable for use in {@link android.widget.ListView} and {@link +android.widget.GridView} components as well as any other components that recycle their child +views. Simply call {@code loadBitmap} where you normally set an image to your {@link +android.widget.ImageView}. For example, in a {@link android.widget.GridView} implementation this +would be in the {@link android.widget.Adapter#getView getView()} method of the backing adapter.</p>
\ No newline at end of file diff --git a/docs/html/training/efficient-downloads/connectivity_patterns.jd b/docs/html/training/efficient-downloads/connectivity_patterns.jd new file mode 100644 index 0000000..81f1540 --- /dev/null +++ b/docs/html/training/efficient-downloads/connectivity_patterns.jd @@ -0,0 +1,76 @@ +page.title=Modifying your Download Patterns Based on the Connectivity Type +parent.title=Transferring Data Without Draining the Battery +parent.link=index.html + +trainingnavtop=true +previous.title=Redundant Downloads are Redundant +previous.link=redundant_redundant.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#WiFi">Use Wi-Fi</a></li> + <li><a href="#Bandwidth">Use greater bandwidth to download more data less often</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li> +</ul> + +</div> +</div> + +<p>When it comes to impact on battery life, not all connection types are created equal. Not only does the Wi-Fi radio use significantly less battery than its wireless radio counterparts, but the radios used in different wireless radio technologies have different battery implications.</p> + +<h2 id="WiFi">Use Wi-Fi</h2> + +<p>In most cases a Wi-Fi radio will offer greater bandwidth at a significantly lower battery cost. As a result, you should endeavor to perform data transfers when connected over Wi-Fi whenever possible.</p> + +<p>You can use a broadcast receiver to listen for connectivity changes that indicate when a Wi-Fi connection has been established to execute significant downloads, preempt scheduled updates, and potentially even temporarily increase the frequency of regular updates as described in <a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a> lesson <a href="{@docRoot}training/monitoring-device-state/connectivity-monitoring.html">Determining and Monitoring the Connectivity Status</a>.</p> + +<h2 id="Bandwidth">Use Greater Bandwidth to Download More Data Less Often</h2> + +<p>When connected over a wireless radio, higher bandwidth generally comes at the price of higher battery cost. Meaning that LTE typically consumes more energy than 3G, which is in turn more expensive than 2G.</p> + +<p>This means that while the underlying radio state machine varies based on the radio technology, generally speaking the relative battery impact of the state change tail-time is greater for higher bandwidth radios.</p> + +<p>At the same time, the higher bandwidth means you can prefetch more aggressively, downloading more data over the same time. Perhaps less intuitively, because the tail-time battery cost is relatively higher, it's also more efficient to keep the radio active for longer periods during each transfer session to reduce the frequency of updates.</p> + +<p>For example, if an LTE radio is has double the bandwidth and double the energy cost of 3G, you should download 4 times as much data during each session—or potentially as much as 10mb. When downloading this much data, it's important to consider the effect of your prefetching on the available local storage and flush your prefetch cache regularly.</p> + +<p>You can use the connectivity manager to determine the active wireless radio, and modify your prefetching routines accordingly:</p> + +<pre>ConnectivityManager cm = + (ConnectivityManager)getSystemService(Context.CONNECTIVITY_SERVICE); + +TelephonyManager tm = + (TelephonyManager)getSystemService(Context.TELEPHONY_SERVICE); + +NetworkInfo activeNetwork = cm.getActiveNetworkInfo(); + +int PrefetchCacheSize = DEFAULT_PREFETCH_CACHE; + +switch (activeNetwork.getType()) { + case (ConnectivityManager.TYPE_WIFI): + PrefetchCacheSize = MAX_PREFETCH_CACHE; break; + case (ConnectivityManager.TYPE_MOBILE): { + switch (tm.getNetworkType()) { + case (TelephonyManager.NETWORK_TYPE_LTE | + TelephonyManager.NETWORK_TYPE_HSPAP): + PrefetchCacheSize *= 4; + break; + case (TelephonyManager.NETWORK_TYPE_EDGE | + TelephonyManager.NETWORK_TYPE_GPRS): + PrefetchCacheSize /= 2; + break; + default: break; + } + break; + } + default: break; +}</pre>
\ No newline at end of file diff --git a/docs/html/training/efficient-downloads/efficient-network-access.jd b/docs/html/training/efficient-downloads/efficient-network-access.jd new file mode 100644 index 0000000..0efad7d --- /dev/null +++ b/docs/html/training/efficient-downloads/efficient-network-access.jd @@ -0,0 +1,170 @@ +page.title=Optimizing Downloads for Efficient Network Access +parent.title=Transferring Data Without Draining the Battery +parent.link=index.html + +trainingnavtop=true +next.title=Minimizing the Effect of Regular Updates +next.link=regular_updates.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#RadioStateMachine">Understand the radio state machine</a></li> + <li><a href="#AppsStateMachine">Understand how apps can impact the radio state machine</a></li> + <li><a href="#PrefetchData">Efficiently prefetch data</a></li> + <li><a href="#BatchTransfers">Batch transfers and connections</a></li> + <li><a href="#ReduceConnections">Reduce the number of connections you use</a></li> + <li><a href="#DDMSNetworkTraffic">Use the DDMS Network Traffic Tool to identify areas of concern</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li> +</ul> + +</div> +</div> + +<p>Using the wireless radio to transfer data is potentially one of your app's most significant sources of battery drain. To minimize the battery drain associated with network activity, it's critical that you understand how your connectivity model will affect the underlying radio hardware.</p> + +<p>This lesson introduces the wireless radio state machine and explains how your app's connectivity model interacts with it. It goes on to propose ways to minimize your data connections, use prefetching, and bundle your transfers in order to minimize the battery drain associated with your data transfers.</p> + +<h2 id="RadioStateMachine">The Radio State Machine</h2> + +<p>A fully active wireless radio consumes significant power, so it transitions between different energy states in order to conserve power when not in use, while attempting to minimize latency associated with "powering up" the radio when it's required.</p> + +<p>The state machine for a typical 3G network radio consists of three energy states: +<ol><li><b>Full power</b>: Used when a connection is active, allowing the device to transfer data at its highest possible rate.</li> +<li><b>Low power</b>: An intermediate state that uses around 50% of the battery power at the full state.</li> +<li><b>Standby</b>: The minimal energy state during which no network connection is active or required.</li> +</ol></p> + +<p>While the low and idle states drain significantly less battery, they also introduce significant latency to network requests. Returning to full power from the low state takes around 1.5 seconds, while moving from idle to full can take over 2 seconds.</p> + +<p>To minimize latency, the state machine uses a delay to postpone the transition to lower energy states. Figure 1 uses AT&T's timings for a typical 3G radio.</p> + +<img src="{@docRoot}images/efficient-downloads/mobile_radio_state_machine.png" /> +<p class="img-caption"><strong>Figure 1.</strong> Typical 3G wireless radio state machine.</p> + +<p>The radio state machine on each device, particularly the associated transition delay ("tail time") and startup latency, will vary based on the wireless radio technology employed (2G, 3G, LTE, etc.) and is defined and configured by the carrier network over which the device is operating.</p> + +<p>This lesson describes a representative state machine for a typical 3G wireless radio, based on <a href="http://www.research.att.com/articles/featured_stories/2011_03/201102_Energy_efficient?fbid=1zObBOMOZSB">data provided by AT&T</a>. However, the general principles and resulting best practices are applicable for all wireless radio implementations.</p> + +<p>This approach is particularly effective for typical web browsing as it prevents unwelcome latency while users browse the web. The relatively low tail-time also ensures that once a browsing session has finished, the radio can move to a lower energy state.</p> + +<p>Unfortunately, this approach can lead to inefficient apps on modern smartphone OSs like Android, where apps run both in the foreground (where latency is important) and in the background (where battery life should be prioritized).</p> + +<h2 id="AppsStateMachine">How Apps Impact the Radio State Machine</h2> + +<p>Every time you create a new network connection, the radio transitions to the full power state. In the case of the typical 3G radio state machine described above, it will remain at full power for the duration of your transfer—plus an additional 5 seconds of tail time—followed by 12 seconds at the low energy state. So for a typical 3G device, every data transfer session will cause the radio to draw energy for almost 20 seconds.</p> + +<p>In practice, this means an app that transfers unbundled data for 1 second every 18 seconds will keep the wireless radio perpetually active, moving it back to high power just as it was about to become idle. As a result, every minute it will consume battery at the high power state for 18 seconds, and at the low power state for the remaining 42 seconds.</p> + +<p>By comparison, the same app that bundles transfers of 3 seconds of every minute will keep the radio in the high power state for only 8 seconds, and will keep it in the low power state for only an additional 12 seconds.</p> + +<p>The second example allows the radio to be idle for an additional 40 second every minute, resulting in a massive reduction in battery consumption.</p> + +<img src="{@docRoot}images/efficient-downloads/graphs.png" /> +<p class="img-caption"><strong>Figure 2.</strong> Relative wireless radio power use for bundled versus unbundled transfers.</p> + +<h2 id="PrefetchData">Prefetch Data</h2> + +<p>Prefetching data is an effective way to reduce the number of independent data transfer sessions. Prefetching allows you to download all the data you are likely to need for a given time period in a single burst, over a single connection, at full capacity.</p> + +<p>By front loading your transfers, you reduce the number of radio activations required to download the data. As a result you not only conserve battery life, but also improve the latency, lower the required bandwidth, and reduce download times.</p> + +<p>Prefetching also provides an improved user experience by minimizing in-app latency caused by waiting for downloads to complete before performing an action or viewing data.</p> + +<p>However, used too aggressively, prefetching introduces the risk of increasing battery drain and bandwidth use—as well as download quota—by downloading data that isn't used. It's also important to ensure that prefetching doesn't delay application startup while the app waits for the prefetch to complete. In practical terms that might mean processing data progressively, or initiating consecutive transfers prioritized such that the data required for application startup is downloaded and processed first.</p> + +<p>How aggressively you prefetch depends on the size of the data being downloaded and the likelihood of it being used. As a rough guide, based on the state machine described above, for data that has a 50% chance of being used within the current user session, you can typically prefetch for around 6 seconds (approximately 1-2 Mb) before the potential cost of downloading unused data matches the potential savings of not downloading that data to begin with.</p> + +<p>Generally speaking, it's good practice to prefetch data such that you will only need to initiate another download every 2 to 5 minutes, and in the order of 1 to 5 megabytes.</p> + +<p>Following this principle, large downloads—such as video files—should be downloaded in chunks at regular intervals (every 2 to 5 minutes), effectively prefetching only the video data likely to be viewed in the next few minutes.</p> + +<p>Note that further downloads should be bundled, as described in the next section, <a href="#BatchTransfers">Batch Transfers and Connections</a>, and that these approximations will vary based on the connection type and speed, as discussed in <a href="connectivity_patterns.html">Modify your Download Patterns Based on the Connectivity Type</a>.</p> + +<p>Let's look at some practical examples:</p> + +<p><b>A music player</b></p> + +<p>You could choose to prefetch an entire album, however should the user stop listening after the first song, you've wasted a significant amount of bandwidth and battery life.</p> + +<p>A better approach would be to maintain a buffer of one song in addition to the one being played. For streaming music, rather than maintaining a continuous stream that keeps the radio active at all times, consider using HTTP live streaming to transmit the audio stream in bursts, simulating the prefetching approach described above.</p> + +<p><b>A news reader</b></p> + +<p>Many news apps attempt to reduce bandwidth by downloading headlines only after a category has been selected, full articles only when the user wants to read them, and thumbnails just as they scroll into view.</p> + +<p>Using this approach, the radio will be forced to remain active for the majority of users' news-reading session as they scroll headlines, change categories, and read articles. Not only that, but the constant switching between energy states will result in significant latency when switching categories or reading articles.</p> + +<p>A better approach would be to prefetch a reasonable amount of data at startup, beginning with the first set of news headlines and thumbnails—ensuring a low latency startup time—and continuing with the remaining headlines and thumbnails, as well as the article text for each article available from at least the primary headline list.</p> + +<p>Another alternative is to prefetch every headline, thumbnail, article text, and possibly even full article pictures—typically in the background on a predetermined schedule. This approach risks spending significant bandwidth and battery life downloading content that's never used, so it should be implemented with caution.</p> + +<p>One solution is to schedule the full download to occur only when connected to Wi-Fi, and possibly only when the device is charging. This is investigated in more detail in <a href="connectivity_patterns.html">Modify your Download Patterns Based on the Connectivity Type</a>.</p> + +<h2 id="BatchTransfers">Batch Transfers and Connections</h2> + +Every time you initiate a connection—irrespective of the size of the associated data transfer—you potentially cause the radio to draw power for nearly 20 seconds when using a typical 3G wireless radio.</p> + +<p>An app that pings the server every 20 seconds, just to acknowledge that the app is running and visible to the user, will keep the radio powered on indefinitely, resulting in a significant battery cost for almost no actual data transfer.</p> + +<p>With that in mind it's important to bundle your data transfers and create a pending transfer queue. Done correctly, you can effectively phase-shift transfers that are due to occur within a similar time window, to make them all happen simultaneously—ensuring that the radio draws power for as short a duration as possible.</p> + +<p>The underlying philosophy of this approach is to transfer as much data as possible during each transfer session in an effort to limit the number of sessions you require.</p> + +<p>That means you should batch your transfers by queuing delay tolerant transfers, and preempting scheduled updates and prefetches, so that they are all executed when time-sensitive transfers are required. Similarly, your scheduled updates and regular prefetching should initiate the execution of your pending transfer queue.</p> + +<p>For a practical example, let's return to the earlier examples from <a href="#PrefetchData">Prefetch Data</a>.</p> + +<p>Take a news application that uses the prefetching routine described above. The news reader collects analytics information to understand the reading patterns of its users and to rank the most popular stories. To keep the news fresh, it checks for updates every hour. To conserve bandwidth, rather than download full photos for each article, it prefetches only thumbnails and downloads the full photos when they are selected.</p> + +<p>In this example, all the analytics information collected within the app should be bundled together and queued for download, rather than being transmitted as it's collected. The resulting bundle should be transferred when either a full-sized photo is being downloaded, or when an hourly update is being performed.</p> + +<p>Any time-sensitive or on-demand transfer—such as downloading a full-sized image—should preempt regularly scheduled updates. The planned update should be executed at the same time as the on-demand transfer, with the next update scheduled to occur after the set interval. This approach mitigates the cost of performing a regular update by piggy-backing on the necessary time-sensitive photo download.</p> + +<h2 id="ReduceConnections">Reduce Connections</h2> + +<p>It's generally more efficient to reuse existing network connections than to initiate new ones. Reusing connections also allows the network to more intelligently react to congestion and related network data issues.</p> + +<p>Rather than creating multiple simultaneous connections to download data, or chaining multiple consecutive GET requests, where possible you should bundle those requests into a single GET.</p> + +<p>For example, it would be more efficient to make a single request for every news article to be returned in a single request / response than to make multiple queries for several news categories. +The wireless radio needs to become active in order to transmit the termination / termination acknowledgement packets associated with server and client timeout, so it's also good practice to close your connections when they aren't in use, rather than waiting for these timeouts.</p> + +<p>That said, closing a connection too early can prevent it from being reused, which then requires additional overhead for establishing a new connection. A useful compromise is not to close the connection immediately, but to still close it before the inherent timeout expires.</p> + +<h2 id="DDMSNetworkTraffic">Use the DDMS Network Traffic Tool to Identify Areas of Concern</h2> + +<p>The Android <a href="{@docRoot}guide/developing/debugging/ddms.html">DDMS (Dalvik Debug Monitor Server)</a> includes a Detailed Network Usage tab that makes it possible to track when your application is making network requests. Using this tool, you can monitor how and when your app transfers data and optimize the underlying code appropriately.</p> + +<p>Figure 3 shows a pattern of transferring small amounts of data roughly 15 seconds apart, suggesting that efficiency could be dramatically improved by prefetching each request or bundling the uploads.</p> + +<img src="{@docRoot}images/efficient-downloads/DDMS.png" /> +<p class="img-caption"><strong>Figure 3.</strong> Tracking network usage with DDMS.</p> + +<p>By monitoring the frequency of your data transfers, and the amount of data transferred during each connection, you can identify areas of your application that can be made more battery-efficient. Generally, you will be looking for short spikes that can be delayed, or that should cause a later transfer to be preempted.</p> + +<p>To better identify the cause of transfer spikes, the Traffic Stats API allows you to tag the data transfers occurring within a thread using the {@code TrafficStats.setThreadStatsTag()} method, followed by manually tagging (and untagging) individual sockets using {@code tagSocket()} and {@code untagSocket()}. For example:</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); +TrafficStats.tagSocket(outputSocket); +// Transfer data using socket +TrafficStats.untagSocket(outputSocket);</pre> + +<p>The Apache {@code HttpClient} and {@code URLConnection} libraries automatically tag sockets based on the current {@code getThreadStatsTag()} value. These libraries also tag and untag sockets when recycled through keep-alive pools.</p> + +<pre>TrafficStats.setThreadStatsTag(0xF00D); +try { + // Make network request using HttpClient.execute() +} finally { + TrafficStats.clearThreadStatsTag(); +}</pre> + +<p>Socket tagging is supported in Android 4.0, but real-time stats will only be displayed on devices running Android 4.0.3 or higher.</p>
\ No newline at end of file diff --git a/docs/html/training/efficient-downloads/index.jd b/docs/html/training/efficient-downloads/index.jd new file mode 100644 index 0000000..a29be91 --- /dev/null +++ b/docs/html/training/efficient-downloads/index.jd @@ -0,0 +1,51 @@ +page.title=Transferring Data Without Draining the Battery + +trainingnavtop=true +startpage=true +next.title=Optimizing Downloads for Efficient Network Access +next.link=efficient-network-access.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<!-- Required platform, tools, add-ons, devices, knowledge, etc. --> +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 2.0 (API Level 5) or higher</li> +</ul> + +<!-- related docs (NOT javadocs) --> +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li> +</ul> + +</div> +</div> + +<p>In this class you will learn to minimize the battery life impact of downloads and network connections, particularly in relation to the wireless radio.</P + +<p>This class demonstrates the best practices for scheduling and executing downloads using techniques such as caching, polling, and prefetching. You will learn how the power-use profile of the wireless radio can affect your choices on when, what, and how to transfer data in order to minimize impact on battery life.</p> + +<h2>Lessons</h2> + +<!-- Create a list of the lessons in this class along with a short description of each lesson. +These should be short and to the point. It should be clear from reading the summary whether someone +will want to jump to a lesson or not.--> + +<dl> + <dt><b><a href="efficient-network-access.html">Optimizing Downloads for Efficient Network Access</a></b></dt> + <dd>This lesson introduces the wireless radio state machine, explains how your app’s connectivity model interacts with it, and how you can minimize your data connection and use prefetching and bundling to minimize the battery drain associated with your data transfers.</dd> + + <dt><b><a href="regular_updates.html">Minimizing the Effect of Regular Updates</a></b></dt> + <dd>This lesson will examine how your refresh frequency can be varied to best mitigate the effect of background updates on the underlying wireless radio state machine.</dd> + + <dt><b><a href="redundant_redundant.html">Redundant Downloads are Redundant</a></b></dt> + <dd>The most fundamental way to reduce your downloads is to download only what you need. This lesson introduces some best practices to eliminate redundant downloads.</dd> + + <dt><b><a href="connectivity_patterns.html">Modifying your Download Patterns Based on the Connectivity Type</a></b></dt> + <dd>When it comes to impact on battery life, not all connection types are created equal. Not only does the Wi-Fi radio use significantly less battery than its wireless radio counterparts, but the radios used in different wireless radio technologies have different battery implications.</dd> + +</dl> diff --git a/docs/html/training/efficient-downloads/redundant_redundant.jd b/docs/html/training/efficient-downloads/redundant_redundant.jd new file mode 100644 index 0000000..4bf9af9 --- /dev/null +++ b/docs/html/training/efficient-downloads/redundant_redundant.jd @@ -0,0 +1,87 @@ +page.title=Redundant Downloads are Redundant +parent.title=Transferring Data Without Draining the Battery +parent.link=index.html + +trainingnavtop=true +previous.title=Minimizing the Effect of Regular Updates +previous.link=regular_updates.html +next.title=Connectivity Based Download Patterns +next.link=connectivity_patterns.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#LocalCache">Cache files locally</a></li> + <li><a href="#ResponseCache">Use the HttpURLConnection response cache</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li> +</ul> + +</div> +</div> + +<p>The most fundamental way to reduce your downloads is to download only what you need. In terms of data, that means implementing REST APIs that allow you to specify query criteria that limit the returned data by using parameters such as the time of your last update.</p> + +<p>Similarly, when downloading images, it's good practice to reduce the size of the images server-side, rather than downloading full-sized images that are reduced on the client.</p> + +<h2 id="LocalCache">Cache Files Locally</h2> + +<p>Another important technique is to avoid downloading duplicate data. You can do this by aggressive caching. Always cache static resources, including on-demand downloads such as full size images, for as long as reasonably possible. On-demand resources should be stored separately to enable you to regularly flush your on-demand cache to manage its size.</p> + +<p>To ensure that your caching doesn't result in your app displaying stale data, be sure to extract the time at which the requested content was last updated, and when it expires, from within the HTTP response headers. This will allow you to determine when the associated content should be refreshed.</p> + +<pre>long currentTime = System.currentTimeMillis()); + +HttpURLConnection conn = (HttpURLConnection) url.openConnection(); + +long expires = conn.getHeaderFieldDate("Expires", currentTime); +long lastModified = conn.getHeaderFieldDate("Last-Modified", currentTime); + +setDataExpirationDate(expires); + +if (lastModified < lastUpdateTime) { + // Skip update +} else { + // Parse update +}</pre> + +<p>Using this approach, you can also effectively cache dynamic content while ensuring it doesn't result in your application displaying stale information.</p> + +<p>You can cache non-sensitive data can in the unmanaged external cache directory:</p> + +<pre>Context.getExternalCacheDir();</pre> + +<p>Alternatively, you can use the managed / secure application cache. Note that this internal cache may be flushed when the system is running low on available storage.</p> + +<pre>Context.getCache();</pre> + +<p>Files stored in either cache location will be erased when the application is uninstalled.</p> + +<h2 id="ResponseCache">Use the HttpURLConnection Response Cache</h2> + +<p>Android 4.0 added a response cache to {@code HttpURLConnection}. You can enable HTTP response caching on supported devices using reflection as follows:</p> + +<pre>private void enableHttpResponseCache() { + try { + long httpCacheSize = 10 * 1024 * 1024; // 10 MiB + File httpCacheDir = new File(getCacheDir(), "http"); + Class.forName("android.net.http.HttpResponseCache") + .getMethod("install", File.class, long.class) + .invoke(null, httpCacheDir, httpCacheSize); + } catch (Exception httpResponseCacheNotAvailable) { + Log.d(TAG, "HTTP response cache is unavailable."); + } +}</pre> + +<p>This sample code will turn on the response cache on Android 4.0+ devices without affecting earlier releases.</p> + +<p>With the cache installed, fully cached HTTP requests can be served directly from local storage, eliminating the need to open a network connection. Conditionally cached responses can validate their freshness from the server, eliminating the bandwidth cost associated with the download.</p> + +<p>Uncached responses get stored in the response cache for for future requests.</p>
\ No newline at end of file diff --git a/docs/html/training/efficient-downloads/regular_updates.jd b/docs/html/training/efficient-downloads/regular_updates.jd new file mode 100644 index 0000000..feb7a8e --- /dev/null +++ b/docs/html/training/efficient-downloads/regular_updates.jd @@ -0,0 +1,102 @@ +page.title=Minimizing the Effect of Regular Updates +parent.title=Transferring Data Without Draining the Battery +parent.link=index.html + +trainingnavtop=true +previous.title=Optimizing Downloads for Efficient Network Access +previous.link=efficient-network-access.html +next.title=Redundant Downloads are Redundant +next.link=redundant_redundant.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#C2DM">Use Cloud to Device Messaging as an alternative to polling</a></li> + <li><a href="#OptimizedPolling">Optimize polling with inexact repeating alarms and exponential back-offs</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a></li> + <li><a href="http://code.google.com/android/c2dm/">Android Cloud to Device Messaging</a></li> +</ul> + +</div> +</div> + +<p>The optimal frequency of regular updates will vary based on device state, network connectivity, user behavior, and explicit user preferences.</p> + +<p><a href="{@docRoot}training/monitoring-device-state/index.html">Optimizing Battery Life</a> discusses how to build battery-efficient apps that modify their refresh frequency based on the state of the host device. That includes disabling background service updates when you lose connectivity and reducing the rate of updates when the battery level is low.</p> + +<p>This lesson will examine how your refresh frequency can be varied to best mitigate the effect of background updates on the underlying wireless radio state machine.</p> + +<h2 id="C2DM">Use Cloud to Device Messaging as an Alternative to Polling</h2> + +<p>Every time your app polls your server to check if an update is required, you activate the wireless radio, drawing power unnecessarily, for up to 20 seconds on a typical 3G connection.</p> + +<p><a href="http://code.google.com/android/c2dm/">Android Cloud to Device Messaging (C2DM)</a> is a lightweight mechanism used to transmit data from a server to a particular app instance. Using C2DM, your server can notify your app running on a particular device that there is new data available for it.</p> + +<p>Compared to polling, where your app must regularly ping the server to query for new data, this event-driven model allows your app to create a new connection only when it knows there is data to download.</p> + +<p>The result is a reduction in unnecessary connections, and a reduced latency for updated data within your application.</p> + +<p>C2DM is implemented using a persistent TCP/IP connection. While it's possible to implement your own push service, it's best practice to use C2DM. This minimizes the number of persistent connections and allows the platform to optimize bandwidth and minimize the associated impact on battery life.</p> + +<h2 id="OptimizedPolling">Optimize Polling with Inexact Repeating Alarms and Exponential Backoffs</h2> + +<p>Where polling is required, it's good practice to set the default data refresh frequency of your app as low as possible without detracting from the user experience.</p> + +<p>A simple approach is to offer preferences to allow users to explicitly set their required update rate, allowing them to define their own balance between data freshness and battery life.</p> + +<p>When scheduling updates, use inexact repeating alarms that allow the system to "phase shift" the exact moment each alarm triggers.</p> + +<pre>int alarmType = AlarmManager.ELAPSED_REALTIME; +long interval = AlarmManager.INTERVAL_HOUR; +long start = System.currentTimeMillis() + interval; + +alarmManager.setInexactRepeating(alarmType, start, interval, pi);</pre> + +<p>If several alarms are scheduled to trigger at similar times, this phase-shifting will cause them to be triggered simultaneously, allowing each update to piggyback on top of a single active radio state change.</p> + +<p>Wherever possible, set your alarm type to {@code ELAPSED_REALTIME} or {@code RTC} rather than to their {@code _WAKEUP} equivalents. This further reduces battery impact by waiting until the phone is no longer in standby mode before the alarm triggers.</p> + +<p>You can further reduce the impact of these scheduled alarms by opportunistically reducing their frequency based on how recently your app was used.</p> + +<p>One approach is to implement an exponential back-off pattern to reduce the frequency of your updates (and / or the degree of prefetching you perform) if the app hasn't been used since the previous update. It's often useful to assert a minimum update frequency and to reset the frequency whenever the app is used, for example:</p> + +<pre>SharedPreferences sp = + context.getSharedPreferences(PREFS, Context.MODE_WORLD_READABLE); + +boolean appUsed = sp.getBoolean(PREFS_APPUSED, false); +long updateInterval = sp.getLong(PREFS_INTERVAL, DEFAULT_REFRESH_INTERVAL); + +if (!appUsed) + if ((updateInterval *= 2) > MAX_REFRESH_INTERVAL) + updateInterval = MAX_REFRESH_INTERVAL; + +Editor spEdit = sp.edit(); +spEdit.putBoolean(PREFS_APPUSED, false); +spEdit.putLong(PREFS_INTERVAL, updateInterval); +spEdit.apply(); + +rescheduleUpdates(updateInterval); +executeUpdateOrPrefetch();</pre> + +<p>You can use a similar exponential back-off pattern to reduce the effect of failed connections and download errors.</p> + +<p>The cost of initiating a network connection is the same whether you are able to contact your server and download data or not. For time-sensitive transfers where successful completion is important, an exponential back-off algorithm can be used to reduce the frequency of retries in order to minimize the associated battery impact, for example:</p> + +<pre>private void retryIn(long interval) { + boolean success = attemptTransfer(); + + if (!success) { + retryIn(interval*2 < MAX_RETRY_INTERVAL ? + interval*2 : MAX_RETRY_INTERVAL); + } +}</pre> + +<p>Alternatively, for transfers that are failure tolerant (such as regular updates), you can simply ignore failed connection and transfer attempts.</p>
\ No newline at end of file diff --git a/docs/html/training/id-auth/custom_auth.jd b/docs/html/training/id-auth/custom_auth.jd index e2bd778..0509c6e 100644 --- a/docs/html/training/id-auth/custom_auth.jd +++ b/docs/html/training/id-auth/custom_auth.jd @@ -181,6 +181,6 @@ multiple copies of it taking up space on your user's device.</p> <p>One solution is to place the service in one small, special-purpose APK. When an app wishes to use your custom account type, it can check the device to see if your custom account service is available. If not, it can direct the user to -Android Market to download the service. This may seem like a great deal of +Google Play to download the service. This may seem like a great deal of trouble at first, but compared with the alternative of re-entering credentials for every app that uses your custom account, it's refreshingly easy.</p> diff --git a/docs/html/training/location/currentlocation.jd b/docs/html/training/location/currentlocation.jd new file mode 100644 index 0000000..4692530 --- /dev/null +++ b/docs/html/training/location/currentlocation.jd @@ -0,0 +1,155 @@ +page.title=Obtaining the Current Location +parent.title=Making Your App Location Aware +parent.link=index.html + +trainingnavtop=true +previous.title=Using the Location Manager +previous.link=locationmanager.html +next.title=Displaying the Location Address +next.link=geocoding.html + + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="currentlocation.html#TaskSetupLocationListener">Set Up the Location Listener</a></li> + <li><a href="currentlocation.html#TaskHandleLocationUpdates">Handle Multiple Sources of Location Updates</a></li> + <li><a href="currentlocation.html#TaskGetLastKnownLocation">Use getLastKnownLocation() Wisely</a></li> + <li><a href="currentlocation.html#TaskTerminateUpdates">Terminate Location Updates</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download + the sample app</a> +<p class="filename">LocationAware.zip</p> +</div> + +</div> +</div> + +<p>After setting up your application to work with {@link android.location.LocationManager}, you can begin to obtain location updates.</p> + +<h2 id="TaskSetupLocationListener">Set Up the Location Listener</h2> + +<p>The {@link android.location.LocationManager} class exposes a number of methods for applications to receive location updates. In its simplest form, you register an event listener, identify the location manager from which you'd like to receive location updates, and specify the minimum time and distance intervals at which to receive location updates. The {@link android.location.LocationListener#onLocationChanged(android.location.Location) onLocationChanged()} callback will be invoked with the frequency that correlates with time and distance intervals.</p> + +<p> +In the sample code snippet below, the location listener is set up to receive notifications at least every 10 seconds and if the device moves by more than 10 meters. The other callback methods notify the application any status change coming from the location provider. +</p> + +<pre> +private final LocationListener listener = new LocationListener() { + + @Override + public void onLocationChanged(Location location) { + // A new location update is received. Do something useful with it. In this case, + // we're sending the update to a handler which then updates the UI with the new + // location. + Message.obtain(mHandler, + UPDATE_LATLNG, + location.getLatitude() + ", " + + location.getLongitude()).sendToTarget(); + + ... + } + ... +}; + +mLocationManager.requestLocationUpdates(LocationManager.GPS_PROVIDER, + 10000, // 10-second interval. + 10, // 10 meters. + listener); +</pre> + +<h2 id="TaskHandleLocationUpdates">Handle Multiple Sources of Location Updates</h2> + +<p>Generally speaking, a location provider with greater accuracy (GPS) requires a longer fix time than one with lower accuracy (network-based). If you want to display location data as quickly as possible and update it as more accurate data becomes available, a common practice is to register a location listener with both GPS and network providers. In the {@link android.location.LocationListener#onLocationChanged(android.location.Location) onLocationChanged()} callback, you'll receive location updates from multiple location providers that may have different timestamps and varying levels of accuracy. You'll need to incorporate logic to disambiguate the location providers and discard updates that are stale and less accurate. The code snippet below demonstrates a sample implementation of this logic.</p> + +<pre> +private static final int TWO_MINUTES = 1000 * 60 * 2; + +/** Determines whether one Location reading is better than the current Location fix + * @param location The new Location that you want to evaluate + * @param currentBestLocation The current Location fix, to which you want to compare the new one + */ +protected boolean isBetterLocation(Location location, Location currentBestLocation) { + if (currentBestLocation == null) { + // A new location is always better than no location + return true; + } + + // Check whether the new location fix is newer or older + long timeDelta = location.getTime() - currentBestLocation.getTime(); + boolean isSignificantlyNewer = timeDelta > TWO_MINUTES; + boolean isSignificantlyOlder = timeDelta < -TWO_MINUTES; + boolean isNewer = timeDelta > 0; + + // If it's been more than two minutes since the current location, use the new location + // because the user has likely moved + if (isSignificantlyNewer) { + return true; + // If the new location is more than two minutes older, it must be worse + } else if (isSignificantlyOlder) { + return false; + } + + // Check whether the new location fix is more or less accurate + int accuracyDelta = (int) (location.getAccuracy() - currentBestLocation.getAccuracy()); + boolean isLessAccurate = accuracyDelta > 0; + boolean isMoreAccurate = accuracyDelta < 0; + boolean isSignificantlyLessAccurate = accuracyDelta > 200; + + // Check if the old and new location are from the same provider + boolean isFromSameProvider = isSameProvider(location.getProvider(), + currentBestLocation.getProvider()); + + // Determine location quality using a combination of timeliness and accuracy + if (isMoreAccurate) { + return true; + } else if (isNewer && !isLessAccurate) { + return true; + } else if (isNewer && !isSignificantlyLessAccurate && isFromSameProvider) { + return true; + } + return false; +} + +/** Checks whether two providers are the same */ +private boolean isSameProvider(String provider1, String provider2) { + if (provider1 == null) { + return provider2 == null; + } + return provider1.equals(provider2); +} +</pre> + +<h2 id="TaskGetLastKnownLocation">Use getLastKnownLocation() Wisely</h2> + +<p>The setup time for getting a reasonable location fix may not be acceptable for certain applications. You should consider calling the {@link android.location.LocationManager#getLastKnownLocation(java.lang.String) getLastKnownLocation()} method which simply queries Android for the last location update previously received by any location providers. Keep in mind that the returned location may be stale. You should check the timestamp and accuracy of the returned location and decide whether it is useful for your application. If you elect to discard the location update returned from {@link android.location.LocationManager#getLastKnownLocation(java.lang.String) getLastKnownLocation()} and wait for fresh updates from the location provider(s), you should consider displaying an appropriate message before location data is received.</p> + +<h2 id="TaskTerminateUpdates">Terminate Location Updates</h2> + +<p>When you are done with using location data, you should terminate location update to reduce unnecessary consumption of power and network bandwidth. For example, if the user navigates away from an activity where location updates are displayed, you should stop location update by calling {@link android.location.LocationManager#removeUpdates(android.location.LocationListener) removeUpdates()} in {@link android.app.Activity#onStop()}. ({@link android.app.Activity#onStop()} is called when the activity is no longer visible. If you want to learn more about activity lifecycle, read up on the <a href="/training/basic-activity-lifecycle/stopping.html">Starting and Stopping an Activity</a> lesson.</p> + +<pre> +protected void onStop() { + super.onStop(); + mLocationManager.removeUpdates(listener); +} +</pre> + +<p class="note"><strong>Note:</strong> For applications that need to continuously receive and process location updates like a near-real time mapping application, it is best to incorporate the location update logic in a background service and make use of the system notification bar to make the user aware that location data is being used.</p>
\ No newline at end of file diff --git a/docs/html/training/location/geocoding.jd b/docs/html/training/location/geocoding.jd new file mode 100644 index 0000000..6364976 --- /dev/null +++ b/docs/html/training/location/geocoding.jd @@ -0,0 +1,98 @@ +page.title=Displaying the Location Address +parent.title=Making Your App Location Aware +parent.link=index.html + +trainingnavtop=true +previous.title=Obtaining the Current Location +previous.link=currentlocation.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="geocoding.html#TaskReverseGeocoding">Perform Reverse Geocoding</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download + the sample app</a> +<p class="filename">LocationAware.zip</p> +</div> + +</div> +</div> + +<p>As shown in previous lessons, location updates are received in the form of latitude and longitude coordinates. While this format is useful for calculating distance or displaying a pushpin on a map, the decimal numbers make no sense to most end users. If you need to display a location to user, it is much more preferable to display the address instead.</p> + +<h2 id="TaskReverseGeocoding">Perform Reverse Geocoding</h2> + +<p>Reverse-geocoding is the process of translating latitude longitude coordinates to a human-readable address. The {@link android.location.Geocoder} API is available for this purpose. Note that behind the scene, the API is dependent on a web service. If such service is unavailable on the device, the API will throw a "Service not Available exception" or return an empty list of addresses. A helper method called {@link android.location.Geocoder#isPresent()} was added in Android 2.3 (API level 9) to check for the existence of the service.</p> + +<p>The following code snippet demonstrates the use of the {@link android.location.Geocoder} API to perform reverse-geocoding. Since the {@link android.location.Geocoder#getFromLocation(double, double, int) getFromLocation()} method is synchronous, you should not invoke it from the UI thread, hence an {@link android.os.AsyncTask} is used in the snippet.</p> + +<pre> +private final LocationListener listener = new LocationListener() { + + public void onLocationChanged(Location location) { + // Bypass reverse-geocoding if the Geocoder service is not available on the + // device. The isPresent() convenient method is only available on Gingerbread or above. + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.GINGERBREAD && Geocoder.isPresent()) { + // Since the geocoding API is synchronous and may take a while. You don't want to lock + // up the UI thread. Invoking reverse geocoding in an AsyncTask. + (new ReverseGeocodingTask(this)).execute(new Location[] {location}); + } + } + ... +}; + +// AsyncTask encapsulating the reverse-geocoding API. Since the geocoder API is blocked, +// we do not want to invoke it from the UI thread. +private class ReverseGeocodingTask extends AsyncTask<Location, Void, Void> { + Context mContext; + + public ReverseGeocodingTask(Context context) { + super(); + mContext = context; + } + + @Override + protected Void doInBackground(Location... params) { + Geocoder geocoder = new Geocoder(mContext, Locale.getDefault()); + + Location loc = params[0]; + List<Address> addresses = null; + try { + // Call the synchronous getFromLocation() method by passing in the lat/long values. + addresses = geocoder.getFromLocation(loc.getLatitude(), loc.getLongitude(), 1); + } catch (IOException e) { + e.printStackTrace(); + // Update UI field with the exception. + Message.obtain(mHandler, UPDATE_ADDRESS, e.toString()).sendToTarget(); + } + if (addresses != null &s;&s; addresses.size() > 0) { + Address address = addresses.get(0); + // Format the first line of address (if available), city, and country name. + String addressText = String.format("%s, %s, %s", + address.getMaxAddressLineIndex() > 0 ? address.getAddressLine(0) : "", + address.getLocality(), + address.getCountryName()); + // Update the UI via a message handler. + Message.obtain(mHandler, UPDATE_ADDRESS, addressText).sendToTarget(); + } + return null; + } +} +</pre>
\ No newline at end of file diff --git a/docs/html/training/location/index.jd b/docs/html/training/location/index.jd new file mode 100644 index 0000000..48cfbc3 --- /dev/null +++ b/docs/html/training/location/index.jd @@ -0,0 +1,51 @@ +page.title=Making Your App Location Aware + +trainingnavtop=true +startpage=true +next.title=Using the Location Manager +next.link=locationmanager.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>Dependencies and prerequisites</h2> + +<ul> + <li>Android 1.0 or higher (2.3+ for the sample app)</li> +</ul> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download + the sample app</a> +<p class="filename">LocationAware.zip</p> +</div> + +</div> +</div> + +<p>Users bring their mobile devices with them almost everywhere. One of the unique features available to mobile applications is location awareness. Knowing the location and using the information wisely can bring a more contextual experience to your users.</p> + +<p>This class teaches you how to incorporate location based services in your Android application. You'll learn a number of methods to receive location updates and related best practices.</p> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="locationmanager.html">Using the Location Manager</a></b></dt> + <dd>Learn how to set up your application before it can receive location updates in Android.</dd> + + <dt><b><a href="currentlocation.html">Obtaining the Current Location</a></b></dt> + <dd>Learn how to work with underlying location technologies available on the platform to obtain current location.</dd> + + <dt><b><a href="geocoding.html">Displaying a Location Address</a></b></dt> + <dd>Learn how to translate location coordinates into addresses that are readable to users.</dd> +</dl> diff --git a/docs/html/training/location/locationmanager.jd b/docs/html/training/location/locationmanager.jd new file mode 100644 index 0000000..5da1205 --- /dev/null +++ b/docs/html/training/location/locationmanager.jd @@ -0,0 +1,90 @@ +page.title=Using the Location Manager +parent.title=Making Your App Location Aware +parent.link=index.html + +trainingnavtop=true +next.title=Obtaining the Current Location +next.link=currentlocation.html + +@jd:body + + +<!-- This is the training bar --> +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="locationmanager.html#TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</a></li> + <li><a href="locationmanager.html#TaskGetLocationManagerRef">Get a Reference to LocationManager</a></li> + <li><a href="locationmanager.html#TaskPickLocationProvider">Pick a Location Provider</a></li> +</ol> + +<h2>You should also read</h2> + +<ul> + <li><a href="{@docRoot}guide/topics/location/index.html">Location and Maps</a></li> +</ul> + +<h2>Try it out</h2> + +<div class="download-box"> +<a href="http://developer.android.com/shareables/training/LocationAware.zip" class="button">Download + the sample app</a> +<p class="filename">LocationAware.zip</p> +</div> + +</div> +</div> + +<p>Before your application can begin receiving location updates, it needs to perform some simple steps to set up access. In this lesson, you'll learn what these steps entail.</p> + +<h2 id="TaskDeclarePermissions">Declare Proper Permissions in Android Manifest</h2> + +<p>The first step of setting up location update access is to declare proper permissions in the manifest. If permissions are missing, the application will get a {@link java.lang.SecurityException} at runtime.</p> + +<p>Depending on the {@link android.location.LocationManager} methods used, either {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} or {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission is needed. For example, you need to declare the {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} permission if your application uses a network-based location provider only. The more accurate GPS requires the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission. +Note that declaring the {@link android.Manifest.permission#ACCESS_FINE_LOCATION} permission implies {@link android.Manifest.permission#ACCESS_COARSE_LOCATION} already.</p> + +<p>Also, if a network-based location provider is used in the application, you'll need to declare the internet permission as well.</p> + +<pre> +<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> +<uses-permission android:name="android.permission.INTERNET" /> +</pre> + +<h2 id="TaskGetLocationManagerRef">Get a Reference to LocationManager</h2> + +<p>{@link android.location.LocationManager} is the main class through which your application can access location services on Android. Similar to other system services, a reference can be obtained from calling the {@link android.content.Context#getSystemService(java.lang.String) getSystemService()} method. If your application intends to receive location updates in the foreground (within an {@link android.app.Activity}), you should usually perform this step in the {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()} method.</p> + +<pre> +LocationManager locationManager = + (LocationManager) this.getSystemService(Context.LOCATION_SERVICE); +</pre> + +<h2 id="TaskPickLocationProvider">Pick a Location Provider</h2> + +<p>While not required, most modern Android-powered devices can receive location updates through multiple underlying technologies, which are abstracted to an application as {@link android.location.LocationProvider} objects. Location providers may have different performance characteristics in terms of time-to-fix, accuracy, monetary cost, power consumption, and so on. Generally, a location provider with a greater accuracy, like the GPS, requires a longer fix time than a less accurate one, such as a network-based location provider.</p> + +<p>Depending on your application's use case, you have to choose a specific location provider, or multiple providers, based on similar tradeoffs. For example, a points of interest check-in application would require higher location accuracy than say, a retail store locator where a city level location fix would suffice. The snippet below asks for a provider backed by the GPS.</p> + +<pre> +LocationProvider provider = + locationManager.getProvider(LocationManager.GPS_PROVIDER); +</pre> + +<p>Alternatively, you can provide some input criteria such as accuracy, power requirement, monetary cost, and so on, and let Android decide a closest match location provider. The snippet below asks for a location provider with fine accuracy and no monetary cost. Note that the criteria may not resolve to any providers, in which case a null will be returned. Your application should be prepared to gracefully handle the situation.</p> + +<pre> +// Retrieve a list of location providers that have fine accuracy, no monetary cost, etc +Criteria criteria = new Criteria(); +criteria.setAccuracy(Criteria.ACCURACY_FINE); +criteria.setCostAllowed(false); +... +String providerName = locManager.getBestProvider(criteria, true); + +// If no suitable provider is found, null is returned. +if (providerName != null) { + ... +} +</pre> diff --git a/docs/html/training/monitoring-device-state/docking-monitoring.jd b/docs/html/training/monitoring-device-state/docking-monitoring.jd index 392ce30..82d655e 100644 --- a/docs/html/training/monitoring-device-state/docking-monitoring.jd +++ b/docs/html/training/monitoring-device-state/docking-monitoring.jd @@ -15,7 +15,7 @@ next.link=connectivity-monitoring.html <h2>This lesson teaches you to</h2> <ol> - <li><a href="#CurrentDockState">Request the Audio Focus</a></li> + <li><a href="#CurrentDockState">Determine the Current Docking State</a></li> <li><a href="#DockType">Determine the Current Dock Type</a></li> <li><a href="#MonitorDockState">Monitor for Changes in the Dock State or Type</a></li> </ol> diff --git a/docs/html/training/multiple-apks/api.jd b/docs/html/training/multiple-apks/api.jd index d8588d4..3492245 100644 --- a/docs/html/training/multiple-apks/api.jd +++ b/docs/html/training/multiple-apks/api.jd @@ -44,7 +44,7 @@ How to have your (Cup)cake and eat it too</a></li> </div> -<p>When developing your Android application to take advantage of multiple APKs on Android Market, +<p>When developing your Android application to take advantage of multiple APKs on Google Play, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each covering a slightly different range of API levels. You will also gain some tools @@ -198,7 +198,7 @@ initialization procedures that don’t change much from APK to APK.</p> <h2 id="AdjustManifests">Adjust the Manifests</h2> -<p>When a user downloads an application which uses multiple APKs through Android Market, the correct +<p>When a user downloads an application which uses multiple APKs through Google Play, the correct APK to use is chosen using two simple rules:</p> <ul> <li>The manifest has to show that particular APK is eligible</li> @@ -278,19 +278,20 @@ green ≥ blue. Therefore we can effectively collapse the chart to look lik </table> <p> -Now, let’s further assume that the Red APK has some requirement on it that the other two don’t. The -Market Filters page of the Android Developer guide has a whole list of possible culprits. For the +Now, let’s further assume that the Red APK has some requirement on it that the other two don’t. +<a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> page of +the Android Developer guide has a whole list of possible culprits. For the sake of example, let’s assume that red requires a front-facing camera. In fact, the entire point of the red APK is to combine the front-facing camera with sweet new functionality that was added in API 11. But, it turns out, not all devices that support API 11 even HAVE front-facing cameras! The horror!</p> -<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the +<p>Fortunately, if a user is browsing Google Play from one such device, Google Play will look at the manifest, see that Red lists the front-facing camera as a requirement, and quietly ignore it, having determined that Red and that device are not a match made in digital heaven. It will then see that Green is not only forward-compatible with devices with API 11 (since no maxSdkVersion was defined), but also doesn’t care whether or not there’s a front-facing camera! The app can still be downloaded -from Android Market by the user, because despite the whole front-camera mishap, there was still an +from Google Play by the user, because despite the whole front-camera mishap, there was still an APK that supported that particular API level.</p> <p> In order to keep all your APKs on separate "tracks", it’s important to have a good version code @@ -330,7 +331,7 @@ Red:11001, 11002, 11003, 11004...</p> </pre> <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2> -<p> Before uploading to Android Market, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all applications being uploaded to Android Market.</p> +<p> Before uploading to Google Play, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all applications being uploaded to Google Play.</p> <ul> <li>All APKs must have the same package name</li> @@ -342,7 +343,7 @@ Red:11001, 11002, 11003, 11004...</p> </ul> <p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t -any surprises that could hide your application in Market. This is actually quite simple using the +any surprises that could hide your application on Google Play. This is actually quite simple using the "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and packaging your Android applications, and is also a very handy tool for inspecting them. </p> @@ -370,10 +371,14 @@ densities: '120' '160' '240' supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values that were added as a result of permissions you set in the manifest. In the example above, the APK won’t be visible to very many devices.</p> -<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since API 11 is Honeycomb (the version of Android optimized specifically for tablets), and no Honeycomb devices have telephony hardware in them, Market will filter out this APK in all cases, until future devices come along which are higher in API level AND possess telephony hardware. +<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since API 11 is Honeycomb (the version of Android optimized specifically for tablets), and no Honeycomb devices have telephony hardware in them, Google Play will filter out this APK in all cases, until future devices come along which are higher in API level AND possess telephony hardware. </p> <p>Fortunately this is easily fixed by adding the following to your manifest:</p> <pre> <uses-feature android:name="android.hardware.telephony" android:required="false" /> </pre> -<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have, to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> +<p>The <code>android.hardware.touchscreen</code> requirement is also implicitly added. If you want your APK to be visible on TVs which are non-touchscreen devices you should add the following to your manifest:</p> +<pre> +<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> +</pre> +<p>Once you’ve completed the pre-launch checklist, upload your APKs to Google Play. It may take a bit for the application to show up when browsing Google Play, but when it does, perform one last check. Download the application onto any test devices you may have, to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> diff --git a/docs/html/training/multiple-apks/index.jd b/docs/html/training/multiple-apks/index.jd index f9b2b43..d92c106 100644 --- a/docs/html/training/multiple-apks/index.jd +++ b/docs/html/training/multiple-apks/index.jd @@ -16,7 +16,7 @@ next.link=api.html <ul> <li>Android 1.0 and higher</li> - <li>You must have an <a href="http://market.android.com/publish">Android Market</a> publisher + <li>You must have an <a href="http://play.google.com/apps/publish">Google Play</a> publisher account</li> </ul> @@ -30,7 +30,7 @@ Support</a></li> </div> </div> -<p>Multiple APK support is a feature in Android Market that allows you to publish multiple APKs +<p>Multiple APK support is a feature of Google Play that allows you to publish multiple APKs under the same application listing. Each APK is a complete instance of your application, optimized to target specific device configurations. Each APK can target a specific set of GL textures, API levels, screen sizes, or some combination thereof.</p> @@ -39,7 +39,7 @@ textures, API levels, screen sizes, or some combination thereof.</p> configuration variables. Each lesson covers basics about how to organize your codebase and target the right devices, as well as the smart way to avoid pitfalls such as unnecessary redundancy across your codebase, and making mistakes in your manifest that could render an APK invisible to all -devices in Android Market. By going through any of these lessons, you'll know how to develop +devices on Google Play. By going through any of these lessons, you'll know how to develop multiple APKs the smart way, make sure they're targeting the devices you want them to, and know how to catch mistakes <em>before</em> your app goes live.</p> diff --git a/docs/html/training/multiple-apks/multiple.jd b/docs/html/training/multiple-apks/multiple.jd index 26a3a93..b30068f 100644 --- a/docs/html/training/multiple-apks/multiple.jd +++ b/docs/html/training/multiple-apks/multiple.jd @@ -40,7 +40,7 @@ Support</a></li> </div> </div> -<p>When developing your Android application to take advantage of multiple APKs on Android Market, +<p>When developing your Android application to take advantage of multiple APKs on Google Play, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each covering a different class of screen size. You will also gain some tools necessary to @@ -227,7 +227,7 @@ initialization procedures that don’t change much from APK to APK.</p> <h2 id="AdjustManifests">Adjust the Manifests</h2> -<p>When a user downloads an application which uses multiple APKs through Android Market, the correct +<p>When a user downloads an application which uses multiple APKs through Google Play, the correct APK to use is chosen using two simple rules: <ul> @@ -329,17 +329,17 @@ preference as follows:</p> Purple ≥ Red ≥ Green ≥ Blue </p><p> Why allow all the overlap? Let’s pretend that the Purple APK has some requirement on it that the -other two don’t. The <a href="{@docRoot}guide/appendix/market-filters.html">Market Filters page</a> +other two don’t. The <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> page of the Android Developer guide has a whole list of possible culprits. For the sake of example, let’s assume that Purple requires a front-facing camera. In fact, the entire point of Purple is to use entertaining things with the front-facing camera! But, it turns out, not all API 11+ devices even HAVE front-facing cameras! The horror!</p> -<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the +<p>Fortunately, if a user is browsing Google Play from one such device, Google Play will look at the manifest, see that Purple lists the front-facing camera as a requirement, and quietly ignore it, having determined that Purple and that device are not a match made in digital heaven. It will then see that Red is not only compatible with xlarge devices, but also doesn’t care whether or not -there’s a front-facing camera! The app can still be downloaded from Android Market by the user, +there’s a front-facing camera! The app can still be downloaded from Google Play by the user, because despite the whole front-camera mishap, there was still an APK that supported that particular API level.</p> @@ -420,9 +420,9 @@ automatically set to false, since that size didn’t exist yet. So be explicit! </p> <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2> -<p> Before uploading to Android Market, double-check the following items. Remember that these are +<p> Before uploading to Google Play, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all -applications being uploaded to Android Market.</p> +applications being uploaded to Google Play.</p> <ul> <li>All APKs must have the same package name.</li> <li>All APKs must be signed with the same certificate.</li> @@ -439,7 +439,7 @@ customizable device emulators in the business sitting on your development machin </ul> <p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t -any surprises that could hide your application in Market. This is actually quite simple using the +any surprises that could hide your application on Google Play. This is actually quite simple using the "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and packaging your Android applications, and is also a very handy tool for inspecting them. </p> @@ -467,11 +467,15 @@ densities: '120' '160' '240' supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values that were added as a result of permissions you set in the manifest. In the example above, the APK will be invisible to most, if not all devices.</p> -<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. +<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Google Play will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. </p> <p>Fortunately this is easily fixed by adding the following to your manifest:<p> <pre> <uses-feature android:name="android.hardware.telephony" android:required="false" /> </pre> +<p>The <code>android.hardware.touchscreen</code> requirement is also implicitly added. If you want your APK to be visible on TVs which are non-touchscreen devices you should add the following to your manifest:</p> +<pre> +<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> +</pre> -<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> +<p>Once you’ve completed the pre-launch checklist, upload your APKs to Google Play. It may take a bit for the application to show up when browsing Google Play, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> diff --git a/docs/html/training/multiple-apks/screensize.jd b/docs/html/training/multiple-apks/screensize.jd index 0ed972a..ac679a7 100644 --- a/docs/html/training/multiple-apks/screensize.jd +++ b/docs/html/training/multiple-apks/screensize.jd @@ -43,7 +43,7 @@ Support</a></li> </div> -<p>When developing your Android application to take advantage of multiple APKs on Android Market, +<p>When developing your Android application to take advantage of multiple APKs on Google Play, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each covering a different class of screen size. You will also gain some tools necessary to @@ -178,7 +178,7 @@ initialization procedures that don’t change much from APK to APK.</p> <h2 id="AdjustManifests">Adjust the Manifests</h2> -<p>When a user downloads an application which uses multiple APKs through Android Market, the correct +<p>When a user downloads an application which uses multiple APKs through Google Play, the correct APK to use is chosen using two simple rules:</p> <ul> <li>The manifest has to show that particular APK is eligible</li> @@ -227,17 +227,17 @@ each APK such that red ≥ green ≥ blue, the chart effectively collaps </table> <p> Now, let’s further assume that the Red APK has some requirement on it that the other two don’t. The -<a href="{@docRoot}guide/appendix/market-filters.html">Market Filters page</a> of the Android +<a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> page of the Android Developer guide has a whole list of possible culprits. For the sake of example, let’s assume that red requires a front-facing camera. In fact, the entire point of the red APK is to use the extra available screen space to do entertaining things with that front-facing camera. But, it turns out, not all xlarge devices even HAVE front-facing cameras! The horror!</p> -<p>Fortunately, if a user is browsing Market from one such device, Android Market will look at the +<p>Fortunately, if a user is browsing Google Play from one such device, Google Play will look at the manifest, see that Red lists the front-facing camera as a requirement, and quietly ignore it, having determined that Red and that device are not a match made in digital heaven. It will then see that Green is not only compatible with xlarge devices, but also doesn’t care whether or not there’s a -front-facing camera! The app can still be downloaded from Android Market by the user, because +front-facing camera! The app can still be downloaded from Google Play by the user, because despite the whole front-camera mishap, there was still an APK that supported that particular screen size.</p> @@ -300,9 +300,9 @@ So be explicit! </p> <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2> -<p> Before uploading to Android Market, double-check the following items. Remember that these are +<p> Before uploading to Google Play, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all -applications being uploaded to Android Market.</p> +applications being uploaded to Google Play.</p> <ul> <li>All APKs must have the same package name</li> <li>All APKs must be signed with the same certificate</li> @@ -317,7 +317,7 @@ customizable device emulators in the business sitting on your development machin </ul> <p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t -any surprises that could hide your application in Market. This is actually quite simple using the +any surprises that could hide your application on Google Play. This is actually quite simple using the "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and packaging your Android applications, and is also a very handy tool for inspecting them. </p> @@ -345,11 +345,16 @@ densities: '120' '160' '240' supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values that were added as a result of permissions you set in the manifest. In the example above, the APK will be invisible to most, if not all devices.</p> -<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. +<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Google Play will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. </p> <p>Fortunately this is easily fixed by adding the following to your manifest:</p> <pre> <uses-feature android:name="android.hardware.telephony" android:required="false" /> </pre> -<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> +<p>The <code>android.hardware.touchscreen</code> requirement is also implicitly added. If you want your APK to be visible on TVs which are non-touchscreen devices you should add the following to your manifest:</p> +<pre> +<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> +</pre> + +<p>Once you’ve completed the pre-launch checklist, upload your APKs to Google Play. It may take a bit for the application to show up when browsing Google Play, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> diff --git a/docs/html/training/multiple-apks/texture.jd b/docs/html/training/multiple-apks/texture.jd index 2bbe511..497d6b8 100644 --- a/docs/html/training/multiple-apks/texture.jd +++ b/docs/html/training/multiple-apks/texture.jd @@ -40,7 +40,7 @@ Support</a></li> </div> </div> -<p>When developing your Android application to take advantage of multiple APKs on Android Market, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each supporting a different subset of OpenGL texture formats. You will also gain some tools necessary to make maintaining a multiple APK codebase as painless as possible.</p> +<p>When developing your Android application to take advantage of multiple APKs on Google Play, it’s important to adopt some good practices from the get-go, and prevent unnecessary headaches further into the development process. This lesson shows you how to create multiple APKs of your app, each supporting a different subset of OpenGL texture formats. You will also gain some tools necessary to make maintaining a multiple APK codebase as painless as possible.</p> <h2 id="Confirm">Confirm You Need Multiple APKs</h2> @@ -158,7 +158,7 @@ initialization procedures that don’t change much from APK to APK.</p> <h2 id="AdjustManifests">Adjust the Manifests</h2> -<p>When a user downloads an application which uses multiple APKs through Android Market, the correct +<p>When a user downloads an application which uses multiple APKs through Google Play, the correct APK to use is chosen using some simple rules:</p> <ul> @@ -246,9 +246,9 @@ following:</p> </pre> <h2 id="PreLaunch">Go Over Pre-launch Checklist</h2> -<p>Before uploading to Android Market, double-check the following items. Remember that these are +<p>Before uploading to Google Play, double-check the following items. Remember that these are specifically relevant to multiple APKs, and in no way represent a complete checklist for all -applications being uploaded to Android Market.</p> +applications being uploaded to Google Play.</p> <ul> <li>All APKs must have the same package name</li> @@ -262,7 +262,7 @@ customizable device emulators in the business sitting on your development machin </ul> <p>It’s also worth inspecting the compiled APK before pushing to market, to make sure there aren’t -any surprises that could hide your application in Market. This is actually quite simple using the +any surprises that could hide your application on Google Play. This is actually quite simple using the "aapt" tool. Aapt (the Android Asset Packaging Tool) is part of the build process for creating and packaging your Android applications, and is also a very handy tool for inspecting them. </p> @@ -290,10 +290,15 @@ densities: '120' '160' '240' supports-screens and compatible-screens, and that you don’t have unintended "uses-feature" values that were added as a result of permissions you set in the manifest. In the example above, the APK will be invisible to most, if not all devices.</p> -<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Market will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. +<p>Why? By adding the required permission SEND_SMS, the feature requirement of android.hardware.telephony was implicitly added. Since most (if not all) xlarge devices are tablets without telephony hardware in them, Google Play will filter out this APK in these cases, until future devices come along which are both large enough to report as xlarge screen size, and possess telephony hardware. </p> <p>Fortunately this is easily fixed by adding the following to your manifest:</p> <pre> <uses-feature android:name="android.hardware.telephony" android:required="false" /> </pre> -<p>Once you’ve completed the pre-launch checklist, upload your APKs to Android Market. It may take a bit for the application to show up when browsing Android Market, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> +<p>The <code>android.hardware.touchscreen</code> requirement is also implicitly added. If you want your APK to be visible on TVs which are non-touchscreen devices you should add the following to your manifest:</p> +<pre> +<uses-feature android:name="android.hardware.touchscreen" android:required="false" /> +</pre> + +<p>Once you’ve completed the pre-launch checklist, upload your APKs to Google Play. It may take a bit for the application to show up when browsing Google Play, but when it does, perform one last check. Download the application onto any test devices you may have to make sure that the APKs are targeting the intended devices. Congratulations, you’re done!</p> diff --git a/docs/html/training/multiscreen/screensizes.jd b/docs/html/training/multiscreen/screensizes.jd index 2db0b67..bf19b08 100644 --- a/docs/html/training/multiscreen/screensizes.jd +++ b/docs/html/training/multiscreen/screensizes.jd @@ -164,14 +164,14 @@ to implement these layouts, you could have the following files:</p> {@sample development/samples/training/multiscreen/newsreader/res/layout/onepane.xml all} </li> - <li><code>res/layout-xlarge/main.xml</code>, two-pane layout: + <li><code>res/layout-large/main.xml</code>, two-pane layout: {@sample development/samples/training/multiscreen/newsreader/res/layout/twopanes.xml all} </li> </ul> -<p>Notice the <code>xlarge</code> qualifier in the directory name of the second layout. This layout -will be selected on devices with screens classified as extra-large (for example, 10" tablets). The +<p>Notice the <code>large</code> qualifier in the directory name of the second layout. This layout +will be selected on devices with screens classified as large (for example, 7" tablets and above). The other layout (without qualifiers) will be selected for smaller devices.</p> @@ -188,7 +188,7 @@ though they are all considered to be "large" screens. That's why Android introdu width given in dp. For example, the typical 7" tablet has a minimum width of 600 dp, so if you want your UI to have two panes on those screens (but a single list on smaller screens), you can use the same two layouts from the previous section for single -and two-pane layouts, but instead of the <code>xlarge</code> size qualifier, use +and two-pane layouts, but instead of the <code>large</code> size qualifier, use <code>sw600dp</code> to indicate the two-pane layout is for screens on which the smallest-width is 600 dp:</p> @@ -209,9 +209,9 @@ while smaller screens will select the <code>layout/main.xml</code> (single-pane) layout.</p> <p>However, this won't work well on pre-3.2 devices, because they don't -recognize <code>sw600dp</code> as a size qualifier, so you still have to use the <code>xlarge</code> +recognize <code>sw600dp</code> as a size qualifier, so you still have to use the <code>large</code> qualifier as well. So, you should have a file named -<code>res/layout-xlarge/main.xml</code> +<code>res/layout-large/main.xml</code> which is identical to <code>res/layout-sw600dp/main.xml</code>. In the next section you'll see a technique that allows you to avoid duplicating the layout files this way.</p> @@ -222,20 +222,20 @@ you'll see a technique that allows you to avoid duplicating the layout files thi Therefore, you should also still use the abstract size bins (small, normal, large and xlarge) to be compatible with earlier versions. For example, if you want to design your UI so that it shows a single-pane UI on phones but a -multi-pane UI on 7" tablets and larger devices, you'd have to supply these +multi-pane UI on 7" tablets, TVs and other large devices, you'd have to supply these files:</p> <p><ul> <li><code>res/layout/main.xml:</code> single-pane layout</li> -<li><code>res/layout-xlarge:</code> multi-pane layout</li> +<li><code>res/layout-large:</code> multi-pane layout</li> <li><code>res/layout-sw600dp:</code> multi-pane layout</li> </ul></p> <p>The last two files are identical, because one of them will be matched by -Android 3.2 devices, and the other one is for the benefit of tablets with +Android 3.2 devices, and the other one is for the benefit of tablets and TVs with earlier versions of Android.</p> -<p>To avoid this duplication of the same file for tablets (and the maintenance +<p>To avoid this duplication of the same file for tablets and TVs (and the maintenance headache resulting from it), you can use alias files. For example, you can define the following layouts:</p> @@ -247,7 +247,7 @@ layouts:</p> <p>And add these two files:</p> <p><ul> -<li><code>res/values-xlarge/layout.xml</code>: +<li><code>res/values-large/layout.xml</code>: <pre> <resources> <item name="main" type="layout">@layout/main_twopanes</item> @@ -267,9 +267,9 @@ layouts:</p> <p>These latter two files have identical content, but they don’t actually define the layout. They merely set up {@code main} to be an alias to {@code main_twopanes}. Since -these files have <code>xlarge</code> and <code>sw600dp</code> selectors, they are -applied to tablets regardless of Android version (pre-3.2 tablets match -{@code xlarge}, and post-3.2 will match <code>sw600dp</code>).</p> +these files have <code>large</code> and <code>sw600dp</code> selectors, they are +applied to tablets and TVs regardless of Android version (pre-3.2 tablets and TVs match +{@code large}, and post-3.2 will match <code>sw600dp</code>).</p> <h2 id="TaskUseOriQuali">Use Orientation Qualifiers</h2> @@ -285,6 +285,7 @@ behaves in each screen size and orientation:</p> <li><b>7" tablet, landscape:</b> dual pane, wide, with action bar</li> <li><b>10" tablet, portrait:</b> dual pane, narrow, with action bar</li> <li><b>10" tablet, landscape:</b> dual pane, wide, with action bar</li> +<li><b>TV, landscape:</b> dual pane, wide, with action bar</li> </ul></p> <p>So each of these layouts is defined in an XML file in the @@ -319,11 +320,11 @@ all} {@sample development/samples/training/multiscreen/newsreader/res/values-sw600dp-port/layouts.xml all} -<p><code>res/values-xlarge-land/layouts.xml</code>:</p> -{@sample development/samples/training/multiscreen/newsreader/res/values-xlarge-land/layouts.xml all} +<p><code>res/values-large-land/layouts.xml</code>:</p> +{@sample development/samples/training/multiscreen/newsreader/res/values-large-land/layouts.xml all} -<p><code>res/values-xlarge-port/layouts.xml</code>:</p> -{@sample development/samples/training/multiscreen/newsreader/res/values-xlarge-port/layouts.xml all} +<p><code>res/values-large-port/layouts.xml</code>:</p> +{@sample development/samples/training/multiscreen/newsreader/res/values-large-port/layouts.xml all} diff --git a/docs/html/training/search/backward-compat.jd b/docs/html/training/search/backward-compat.jd new file mode 100644 index 0000000..0894fa9 --- /dev/null +++ b/docs/html/training/search/backward-compat.jd @@ -0,0 +1,87 @@ +page.title=Remaining Backward Compatible +trainingnavtop=true +previous.title=Storing and Searching for Data +previous.link=search.html + +@jd:body + + <div id="tb-wrapper"> + <div id="tb"> + <h2>This lesson teaches you to</h2> + + <ul> + <li><a href="{@docRoot}training/search/backward-compat.html#set-sdk">Set Minimum + and Target API levels</a></li> + + <li><a href="{@docRoot}training/search/backward-compat.html#provide-sd">Provide the Search + Dialog for Older Devices</a></li> + + <li><a href="{@docRoot}training/search/backward-compat.html#check-ver">Check the Android Build + Version at Runtime</a></li> + </ul> + </div> + </div> + + <p>The {@link android.widget.SearchView} and action bar are only available on Android 3.0 and + later. To support older platforms, you can fall back to the search dialog. The search dialog is a + system provided UI that overlays on top of your application when invoked.</p> + + <h2 id="set-sdk">Set Minimum and Target API levels</h2> + + <p>To setup the search dialog, first declare in your manifest that you want to support older + devices, but want to target Android 3.0 or later versions. When you do this, your application + automatically uses the action bar on Android 3.0 or later and uses the traditional menu system on + older devices:</p> + <pre> +<uses-sdk android:minSdkVersion="7" android:targetSdkVersion="15" /> + +<application> +... +</pre> + + <h2 id="provide-sd">Provide the Search Dialog for Older Devices</h2> + + <p>To invoke the search dialog on older devices, call {@link + android.app.Activity#onSearchRequested onSearchRequested()} whenever a user selects the search + menu item from the options menu. Because Android 3.0 and higher devices show the + {@link android.widget.SearchView} in the action bar (as demonstrated in the first lesson), only versions + older than 3.0 call {@link android.app.Activity#onOptionsItemSelected onOptionsItemSelected()} when the + user selects the search menu item. + </p> + <pre> +@Override +public boolean onOptionsItemSelected(MenuItem item) { + switch (item.getItemId()) { + case R.id.search: + onSearchRequested(); + return true; + default: + return false; + } +} +</pre> + + <h2 id="check-ver">Check the Android Build Version at Runtime</h2> + + <p>At runtime, check the device version to make sure an unsupported use of {@link + android.widget.SearchView} does not occur on older devices. In our example code, this happens in + the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method:</p> + <pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.options_menu, menu); + + if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.HONEYCOMB) { + SearchManager searchManager = + (SearchManager) getSystemService(Context.SEARCH_SERVICE); + SearchView searchView = + (SearchView) menu.findItem(R.id.search).getActionView(); + searchView.setSearchableInfo( + searchManager.getSearchableInfo(getComponentName())); + searchView.setIconifiedByDefault(false); + } + return true; +} +</pre> diff --git a/docs/html/training/search/index.jd b/docs/html/training/search/index.jd new file mode 100644 index 0000000..bfd1618 --- /dev/null +++ b/docs/html/training/search/index.jd @@ -0,0 +1,53 @@ +page.title=Adding Search Functionality +trainingnavtop=true +startpage=true +next.title=Setting Up the Search Interface +next.link=setup.html + +@jd:body + + <div id="tb-wrapper"> + <div id="tb"> + <h2>Dependencies and prerequisites</h2> + + <ul> + <li>Android 3.0 or later (with some support for Android 2.1)</li> + + <li>Experience building an Android <a href="{@docRoot}guide/topics/ui/index.html">User + Interface</a></li> + </ul> + + <h2>You should also read</h2> + + <ul> + <li><a href="{@docRoot}guide/topics/search/index.html">Search</a></li> + + <li><a href="{@docRoot}resources/samples/SearchableDictionary/index.html">Searchable + Dictionary Sample App</a></li> + </ul> + </div> + </div> + + <p>Android's built-in search features offer apps an easy way to provide a + consistent search experience for all users. There are two ways to implement search in your app + depending on the version of Android that is running on the device. This class covers how to add + search with {@link android.widget.SearchView}, which was introduced in Android 3.0, while + maintaining backward compatibility with older versions of Android by using the default search + dialog provided by the system.</p> + + <h2>Lessons</h2> + + <dl> + <dt><b><a href="setup.html">Setting Up the Search Interface</a></b></dt> + + <dd>Learn how to add a search interface to your app and how to configure an activity to handle + search queries.</dd> + + <dt><b><a href="search.html">Storing and Searching for Data</a></b></dt> + + <dd>Learn a simple way to store and search for data in a SQLite virtual database table.</dd> + + <dt><b><a href="backward-compat.html">Remaining Backward Compatible</a></b></dt> + + <dd>Learn how to keep search features backward compatible with older devices by using.</dd> + </dl>
\ No newline at end of file diff --git a/docs/html/training/search/search.jd b/docs/html/training/search/search.jd new file mode 100644 index 0000000..17e7640 --- /dev/null +++ b/docs/html/training/search/search.jd @@ -0,0 +1,217 @@ +page.title=Storing and Searching for Data +trainingnavtop=true +previous.title=Setting Up the Search Interface +previous.link=setup.html +next.title=Remaining Backward Compatible +next.link=backward-compat.html + +@jd:body + + <div id="tb-wrapper"> + <div id="tb"> + <h2>This lesson teaches you to</h2> + + <ul> + <li><a href="{@docRoot}training/search/search.html#create">Create the Virtual + Table</a></li> + + <li><a href="{@docRoot}training/search/search.html#populate">Populate the Virtual + Table</a></li> + + <li><a href="{@docRoot}training/search/search.html#search">Search for the Query</a></li> + </ul> + </div> + </div> + + <p>There are many ways to store your data, such as in an online database, in a local SQLite + database, or even in a text file. It is up to you to decide what is the best solution for your + application. This lesson shows you how to create a SQLite virtual table that can provide robust + full-text searching. The table is populated with data from a text file that contains a word and + definition pair on each line in the file.</p> + + <h2 id="create">Create the Virtual Table</h2> + + <p>A virtual table behaves similarly to a SQLite table, but reads and writes to an object in + memory via callbacks, instead of to a database file. To create a virtual table, create a class + for the table:</p> + <pre> +public class DatabaseTable { + private final DatabaseOpenHelper mDatabaseOpenHelper; + + public DatabaseTable(Context context) { + mDatabaseOpenHelper = new DatabaseOpenHelper(context); + } +} +</pre> + + <p>Create an inner class in <code>DatabaseTable</code> that extends {@link + android.database.sqlite.SQLiteOpenHelper}. The {@link android.database.sqlite.SQLiteOpenHelper} class + defines abstract methods that you must override so that your database table can be created and + upgraded when necessary. For example, here is some code that declares a database table that will + contain words for a dictionary app:</p> + <pre> +public class DatabaseTable { + + private static final String TAG = "DictionaryDatabase"; + + //The columns we'll include in the dictionary table + public static final String COL_WORD = "WORD"; + public static final String COL_DEFINITION = "DEFINITION"; + + private static final String DATABASE_NAME = "DICTIONARY"; + private static final String FTS_VIRTUAL_TABLE = "FTS"; + private static final int DATABASE_VERSION = 1; + + private final DatabaseOpenHelper mDatabaseOpenHelper; + + public DatabaseTable(Context context) { + mDatabaseOpenHelper = new DatabaseOpenHelper(context); + } + + private static class DatabaseOpenHelper extends SQLiteOpenHelper { + + private final Context mHelperContext; + private SQLiteDatabase mDatabase; + + private static final String FTS_TABLE_CREATE = + "CREATE VIRTUAL TABLE " + FTS_VIRTUAL_TABLE + + " USING fts3 (" + + COL_WORD + ", " + + COL_DEFINITION + ")"; + + DatabaseOpenHelper(Context context) { + super(context, DATABASE_NAME, null, DATABASE_VERSION); + mHelperContext = context; + } + + @Override + public void onCreate(SQLiteDatabase db) { + mDatabase = db; + mDatabase.execSQL(FTS_TABLE_CREATE); + } + + @Override + public void onUpgrade(SQLiteDatabase db, int oldVersion, int newVersion) { + Log.w(TAG, "Upgrading database from version " + oldVersion + " to " + + newVersion + ", which will destroy all old data"); + db.execSQL("DROP TABLE IF EXISTS " + FTS_VIRTUAL_TABLE); + onCreate(db); + } + } +} +</pre> + + <h2 id="populate">Populate the Virtual Table</h2> + + <p>The table now needs data to store. The following code shows you how to read a text file + (located in <code>res/raw/definitions.txt</code>) that contains words and their definitions, how + to parse that file, and how to insert each line of that file as a row in the virtual table. This + is all done in another thread to prevent the UI from locking. Add the following code to your + <code>DatabaseOpenHelper</code> inner class.</p> + + <p class="note"><strong>Tip:</strong> You also might want to set up a callback to notify your UI + activity of this thread's completion.</p> + <pre> +private void loadDictionary() { + new Thread(new Runnable() { + public void run() { + try { + loadWords(); + } catch (IOException e) { + throw new RuntimeException(e); + } + } + }).start(); + } + +private void loadWords() throws IOException { + final Resources resources = mHelperContext.getResources(); + InputStream inputStream = resources.openRawResource(R.raw.definitions); + BufferedReader reader = new BufferedReader(new InputStreamReader(inputStream)); + + try { + String line; + while ((line = reader.readLine()) != null) { + String[] strings = TextUtils.split(line, "-"); + if (strings.length < 2) continue; + long id = addWord(strings[0].trim(), strings[1].trim()); + if (id < 0) { + Log.e(TAG, "unable to add word: " + strings[0].trim()); + } + } + } finally { + reader.close(); + } +} + +public long addWord(String word, String definition) { + ContentValues initialValues = new ContentValues(); + initialValues.put(COL_WORD, word); + initialValues.put(COL_DEFINITION, definition); + + return mDatabase.insert(FTS_VIRTUAL_TABLE, null, initialValues); +} +</pre> + + <p>Call the <code>loadDictionary()</code> method wherever appropriate to populate the table. A + good place would be in the {@link android.database.sqlite.SQLiteOpenHelper#onCreate onCreate()} + method of the <code>DatabaseOpenHelper</code> class, right after you create the table:</p> + <pre> +@Override +public void onCreate(SQLiteDatabase db) { + mDatabase = db; + mDatabase.execSQL(FTS_TABLE_CREATE); + loadDictionary(); +} +</pre> + + <h2 id="search">Search for the Query</h2> + + <p>When you have the virtual table created and populated, use the query supplied by your {@link + android.widget.SearchView} to search the data. Add the following methods to the + <code>DatabaseTable</code> class to build a SQL statement that searches for the query:</p> + <pre> +public Cursor getWordMatches(String query, String[] columns) { + String selection = COL_WORD + " MATCH ?"; + String[] selectionArgs = new String[] {query+"*"}; + + return query(selection, selectionArgs, columns); +} + +private Cursor query(String selection, String[] selectionArgs, String[] columns) { + SQLiteQueryBuilder builder = new SQLiteQueryBuilder(); + builder.setTables(FTS_VIRTUAL_TABLE); + + Cursor cursor = builder.query(mDatabaseOpenHelper.getReadableDatabase(), + columns, selection, selectionArgs, null, null, null); + + if (cursor == null) { + return null; + } else if (!cursor.moveToFirst()) { + cursor.close(); + return null; + } + return cursor; +} +</pre> + + <p>Search for a query by calling <code>getWordMatches()</code>. Any matching results are returned + in a {@link android.database.Cursor} that you can iterate through or use to build a {@link android.widget.ListView}. + This example calls <code>getWordMatches()</code> in the <code>handleIntent()</code> method of the searchable + activity. Remember that the searchable activity receives the query inside of the {@link + android.content.Intent#ACTION_SEARCH} intent as an extra, because of the intent filter that you + previously created:</p> + <pre> +DatabaseTable db = new DatabaseTable(this); + +... + +private void handleIntent(Intent intent) { + + if (Intent.ACTION_SEARCH.equals(intent.getAction())) { + String query = intent.getStringExtra(SearchManager.QUERY); + Cursor c = db.getWordMatches(query, null); + //process Cursor and display results + } +} +</pre>
\ No newline at end of file diff --git a/docs/html/training/search/setup.jd b/docs/html/training/search/setup.jd new file mode 100644 index 0000000..044e422 --- /dev/null +++ b/docs/html/training/search/setup.jd @@ -0,0 +1,197 @@ +page.title=Setting Up the Search Interface +trainingnavtop=true +next.title=Storing and Searching for Data +next.link=search.html + +@jd:body + + <div id="tb-wrapper"> + <div id="tb"> + <h2>This lesson teaches you to</h2> + + <ul> + <li><a href="{@docRoot}training/search/setup.html#add-sv">Add the Search View to the Action + Bar</a></li> + + <li><a href="{@docRoot}training/search/setup.html#create-sc">Create a Searchable + Configuration</a></li> + + <li><a href="{@docRoot}training/search/setup.html#create-sa">Create a Searchable + Activity</a></li> + </ul> + + <h2>You should also read:</h2> + + <ul> + <li><a href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a></li> + </ul> + </div> + </div> + + <p>Beginning in Android 3.0, using the {@link android.widget.SearchView} widget as an item in + the action bar is the preferred way to provide search in your app. Like with all items in + the action bar, you can define the {@link android.widget.SearchView} to show at all times, only + when there is room, or as a collapsible action, which displays the {@link + android.widget.SearchView} as an icon initially, then takes up the entire action bar as a search + field when the user clicks the icon.</p> + + <p class="note"><strong>Note:</strong> Later in this class, you will learn how to make your + app compatible down to Android 2.1 (API level 7) for devices that do not support + {@link android.widget.SearchView}.</p> + + <h2 id="add-sv">Add the Search View to the Action Bar</h2> + + <p>To add a {@link android.widget.SearchView} widget to the action bar, create a file named + <code>res/menu/options_menu.xml</code> in your project and add the following code to the file. + This code defines how to create the search item, such as the icon to use and the title of the + item. The <code>collapseActionView</code> attribute allows your {@link android.widget.SearchView} + to expand to take up the whole action bar and collapse back down into a + normal action bar item when not in use. Because of the limited action bar space on handset devices, + using the <code>collapsibleActionView</code> attribute is recommended to provide a better + user experience.</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> +<menu xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:id="@+id/search" + android:title="@string/search_title" + android:icon="@drawable/ic_search" + android:showAsAction="collapseActionView|ifRoom" + android:actionViewClass="android.widget.SearchView" /> +</menu> +</pre> + + <p class="note"><strong>Note:</strong> If you already have an existing XML file for your menu + items, you can add the <code><item></code> element to that file instead.</p> + + <p>To display the {@link android.widget.SearchView} in the action bar, inflate the XML menu + resource (<code>res/menu/options_menu.xml</code>) in the {@link + android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method of your activity:</p> + <pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.options_menu, menu); + + return true; +} +</pre> + + <p>If you run your app now, the {@link android.widget.SearchView} appears in your app's action + bar, but it isn't functional. You now need to define <em>how</em> the {@link + android.widget.SearchView} behaves.</p> + + <h2 id="create-sc">Create a Searchable Configuration</h2> + + <p>A <a href="http://developer.android.com/guide/topics/search/searchable-config.html">searchable + configuration</a> defines how the {@link android.widget.SearchView} behaves and is defined in a + <code>res/xml/searchable.xml</code> file. At a minimum, a searchable configuration must contain + an <code>android:label</code> attribute that has the same value as the + <code>android:label</code> attribute of the <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> or + <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> element in your Android manifest. + However, we also recommend adding an <code>android:hint</code> attribute to give the user an idea of what to enter into the search + box:</p> + <pre> +<?xml version="1.0" encoding="utf-8"?> + +<searchable xmlns:android="http://schemas.android.com/apk/res/android" + android:label="@string/app_name" + android:hint="@string/search_hint" /> +</pre> + + <p>In your application's manifest file, declare a <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"> + <code><meta-data></code></a> element that points to the <code>res/xml/searchable.xml</code> file, + so that your application knows where to find it. Declare the element in an <code><activity></code> + that you want to display the {@link android.widget.SearchView} in:</p> + <pre> +<activity ... > + ... + <meta-data android:name="android.app.searchable" + android:resource="@xml/searchable" /> + +</activity> +</pre> + + <p>In the {@link android.app.Activity#onCreateOptionsMenu onCreateOptionsMenu()} method that you + created before, associate the searchable configuration with the {@link android.widget.SearchView} + by calling {@link android.widget.SearchView#setSearchableInfo}:</p> + <pre> +@Override +public boolean onCreateOptionsMenu(Menu menu) { + MenuInflater inflater = getMenuInflater(); + inflater.inflate(R.menu.options_menu, menu); + + // Associate searchable configuration with the SearchView + SearchManager searchManager = + (SearchManager) getSystemService(Context.SEARCH_SERVICE); + SearchView searchView = + (SearchView) menu.findItem(R.id.search).getActionView(); + searchView.setSearchableInfo( + searchManager.getSearchableInfo(getComponentName())); + + return true; +} +</pre> + + <p>The call to {@link android.app.SearchManager#getSearchableInfo getSearchableInfo()} obtains a + {@link android.app.SearchableInfo} object that is created from the searchable configuration XML + file. When the searchable configuration is correctly associated with your {@link + android.widget.SearchView}, the {@link android.widget.SearchView} starts an activity with the + {@link android.content.Intent#ACTION_SEARCH} intent when a user submits a query. You now need an + activity that can filter for this intent and handle the search query.</p> + + <h2 id="create-sa">Create a Searchable Activity</h2> + + <p>A {@link android.widget.SearchView} tries to start an activity with the {@link + android.content.Intent#ACTION_SEARCH} when a user submits a search query. A searchable activity + filters for the {@link android.content.Intent#ACTION_SEARCH} intent and searches for the query in + some sort of data set. To create a searchable activity, declare an activity of your choice to + filter for the {@link android.content.Intent#ACTION_SEARCH} intent:</p> + <pre> +<activity android:name=".SearchResultsActivity" ... > + ... + <intent-filter> + <action android:name="android.intent.action.SEARCH" /> + </intent-filter> + ... +</activity> +</pre> + + <p>In your searchable activity, handle the {@link android.content.Intent#ACTION_SEARCH} intent by + checking for it in your {@link android.app.Activity#onCreate onCreate()} method.</p> + + <p class="note"><strong>Note:</strong> If your searchable activity launches in single top mode + (<code>android:launchMode="singleTop"</code>), also handle the {@link + android.content.Intent#ACTION_SEARCH} intent in the {@link android.app.Activity#onNewIntent + onNewIntent()} method. In single top mode, only one instance of your activity is created and + subsequent calls to start your activity do not create a new activity on the + stack. This launch mode is useful so users can perform searches from the same activity + without creating a new activity instance every time.</p> + <pre> +public class SearchResultsActivity extends Activity { + + @Override + public void onCreate(Bundle savedInstanceState) { + ... + handleIntent(getIntent()); + } + + @Override + protected void onNewIntent(Intent intent) { + ... + handleIntent(intent); + } + + private void handleIntent(Intent intent) { + + if (Intent.ACTION_SEARCH.equals(intent.getAction())) { + String query = intent.getStringExtra(SearchManager.QUERY); + //use the query to search your data somehow + } + } + ... +} +</pre> + + <p>If you run your app now, the {@link android.widget.SearchView} can accept the user's query and + start your searchable activity with the {@link android.content.Intent#ACTION_SEARCH} intent. It + is now up to you to figure out how to store and search your data given a query.</p>
\ No newline at end of file diff --git a/docs/html/training/sharing/receive.jd b/docs/html/training/sharing/receive.jd index cc55967..a0a5bc8 100644 --- a/docs/html/training/sharing/receive.jd +++ b/docs/html/training/sharing/receive.jd @@ -34,7 +34,7 @@ Intent Filters</a></li> from applications. Think about how users interact with your application, and what data types you want to receive from other applications. For example, a social networking application would likely be interested in receiving text content, like an interesting web URL, from another app. The -<a href="https://market.android.com/details?id=com.google.android.apps.plus">Google+ Android +<a href="https://play.google.com/store/details?id=com.google.android.apps.plus">Google+ Android application</a> accepts both text <em>and</em> single or multiple images. With this app, a user can easily start a new Google+ post with photos from the Android Gallery app.</p> diff --git a/docs/html/training/tv/index.jd b/docs/html/training/tv/index.jd new file mode 100644 index 0000000..ae13c4a --- /dev/null +++ b/docs/html/training/tv/index.jd @@ -0,0 +1,52 @@ +page.title=Designing for TV + +trainingnavtop=true +startpage=true +next.title=Optimizing layouts for TV +next.link=optimizing-layouts-tv.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<!-- Required platform, tools, add-ons, devices, knowledge, etc. --> +<h2>Dependencies and prerequisites</h2> +<ul> + <li>Android 2.0 (API Level 5) or higher</li> +</ul> + +</div> +</div> +<p> + Smart TVs powered by Android bring your favorite Android apps to the best screen in your house. + Thousands of apps in the Google Play Store are already optimized for TVs. This class shows how + you can optimize your Android app for TVs, including how to build a layout that + works great when the user is ten feet away and navigating with a remote control. +</p> + +<h2>Lessons</h2> + +<dl> + <dt><b><a href="optimizing-layouts-tv.html">Optimizing Layouts for TV</a></b></dt> + <dd>Shows you how to optimize app layouts for TV screens, which have some unique characteristics such as: + <ul> + <li>permanent "landscape" mode</li> + <li>high-resolution displays</li> + <li>"10 foot UI" environment.</li> + </ul> + </dd> + + <dt><b><a href="optimizing-navigation-tv.html">Optimizing Navigation for TV</a></b></dt> + <dd>Shows you how to design navigation for TVs, including: + <ul> + <li>handling D-pad navigation</li> + <li>providing navigational feedback</li> + <li>providing easily-accessible controls on the screen.</li> + </ul> + </dd> + + <dt><b><a href="unsupported-features-tv.html">Handling features not supported on TV</a></b></dt> + <dd>Lists the hardware features that are usually not available on TVs. This lesson also shows you how to + provide alternatives for missing features or check for missing features and disable code at run time.</dd> +</dl>
\ No newline at end of file diff --git a/docs/html/training/tv/optimizing-layouts-tv.jd b/docs/html/training/tv/optimizing-layouts-tv.jd new file mode 100644 index 0000000..6eac6d3 --- /dev/null +++ b/docs/html/training/tv/optimizing-layouts-tv.jd @@ -0,0 +1,246 @@ +page.title=Optimizing Layouts for TV +parent.title=Designing for TV +parent.link=index.html + +trainingnavtop=true +next.title=Optimizing Navigation for TV +next.link=optimizing-navigation-tv.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#DesignLandscapeLayouts">Design Landscape Layouts</a></li> + <li><a href="#MakeTextControlsEasyToSee">Make Text and Controls Easy to See</a></li> + <li><a href="#DesignForLargeScreens">Design for High-Density Large Screens</a></li> + <li><a href="#HandleLargeBitmaps">Handle Large Bitmaps in Your Application</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li> +</ul> + +</div> +</div> + +<p> +When your application is running on a television set, you should assume that the user is sitting about +ten feet away from the screen. This user environment is referred to as the +<a href="http://en.wikipedia.org/wiki/10-foot_user_interface">10-foot UI</a>. To provide your +users with a usable and enjoyable experience, you should style and lay out your UI accordingly.. +</p> +<p> +This lesson shows you how to optimize layouts for TV by: +</p> +<ul> + <li>Providing appropriate layout resources for landscape mode.</li> + <li>Ensuring that text and controls are large enough to be visible from a distance.</li> + <li>Providing high resolution bitmaps and icons for HD TV screens.</li> +</ul> + +<h2 id="DesignLandscapeLayouts">Design Landscape Layouts</h2> + +<p> +TV screens are always in landscape orientation. Follow these tips to build landscape layouts optimized for TV screens: +</p> +<ul> + <li>Put on-screen navigational controls on the left or right side of the screen and save the + vertical space for content.</li> + <li>Create UIs that are divided into sections, by using <a href="{@docRoot}guide/topics/fundamentals/fragments.html">Fragments</a> + and use view groups like {@link android.widget.GridView} instead + of {@link android.widget.ListView} to make better use of the + horizontal screen space.</li> + <li>Use view groups such as {@link android.widget.RelativeLayout} + or {@link android.widget.LinearLayout} to arrange views. + This allows the Android system to adjust the position of the views to the size, alignment, + aspect ratio, and pixel density of the TV screen.</li> + <li>Add sufficient margins between layout controls to avoid a cluttered UI.</li> +</ul> + +<p> +For example, the following layout is optimized for TV: +</p> + +<img src="{@docRoot}images/training/panoramio-grid.png" /> + +<p> +In this layout, the controls are on the lefthand side. The UI is displayed within a +{@link android.widget.GridView}, which is well-suited to landscape orientation. +In this layout both GridView and Fragment have the width and height set +dynamically, so they can adjust to the screen resolution. Controls are added to the left side Fragment programatically at runtime. +The layout file for this UI is {@code res/layout-land-large/photogrid_tv.xml}. +(This layout file is placed in {@code layout-land-large} because TVs have large screens with landscape orientation. For details refer to +<a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.)</p> + +res/layout-land-large/photogrid_tv.xml +<pre> +<RelativeLayout + android:layout_width="fill_parent" + android:layout_height="fill_parent" > + + <fragment + android:id="@+id/leftsidecontrols" + android:layout_width="0dip" + android:layout_marginLeft="5dip" + android:layout_height="match_parent" /> + + <GridView + android:id="@+id/gridview" + android:layout_width="wrap_content" + android:layout_height="wrap_content" /> + +</RelativeLayout> +</pre> + +<p> +To set up action bar items on the left side of the screen, you can also include the <a +href="http://code.google.com/p/googletv-android-samples/source/browse/#git%2FLeftNavBarLibrary"> +Left navigation bar library</a> in your application to set up action items on the left side +of the screen, instead of creating a custom Fragment to add controls: +</p> + +<pre> +LeftNavBar bar = (LeftNavBarService.instance()).getLeftNavBar(this); +</pre> + +<p> +When you have an activity in which the content scrolls vertically, always use a left navigation bar; +otherwise, your users have to scroll to the top of the content to switch between the content view and +the ActionBar. Look at the +<a href="http://code.google.com/p/googletv-android-samples/source/browse/#git%2FLeftNavBarDemo"> +Left navigation bar sample app</a> to see how to simple it is to include the left navigation bar in your app. +</p> + +<h2 id="MakeTextControlsEasyToSee">Make Text and Controls Easy to See</h2> +<p> +The text and controls in a TV application's UI should be easily visible and navigable from a distance. +Follow these tips to make them easier to see from a distance : +</p> + +<ul> + <li>Break text into small chunks that users can quickly scan.</li> + <li>Use light text on a dark background. This style is easier to read on a TV.</li> + <li>Avoid lightweight fonts or fonts that have both very narrow and very broad strokes. Use simple sans-serif + fonts and use anti-aliasing to increase readability.</li> + <li>Use Android's standard font sizes: + <pre> + <TextView + android:id="@+id/atext" + android:layout_width="wrap_content" + android:layout_height="wrap_content" + android:gravity="center_vertical" + android:singleLine="true" + android:textAppearance="?android:attr/textAppearanceMedium"/> + </pre></li> + <li>Ensure that all your view widgets are large enough to be clearly visible to someone sitting 10 feet away + from the screen (this distance is greater for very large screens). The best way to do this is to use + layout-relative sizing rather than absolute sizing, and density-independent pixel units instead of absolute + pixel units. For example, to set the width of a widget, use wrap_content instead of a pixel measurement, + and to set the margin for a widget, use dip instead of px values. + </li> +</ul> +<p> + +</p> + +<h2 id="DesignForLargeScreens">Design for High-Density Large Screens</h2> + +<p> +The common HDTV display resolutions are 720p, 1080i, and 1080p. Design your UI for 1080p, and then +allow the Android system to downscale your UI to 720p if necessary. In general, downscaling (removing pixels) +does not degrade the UI (Notice that the converse is not true; you should avoid upscaling because it degrades +UI quality). +</p> + +<p> +To get the best scaling results for images, provide them as <a href="{@docRoot}guide/developing/tools/draw9patch.html"> +9-patch image</a> elements if possible. +If you provide low quality or small images in your layouts, they will appear pixelated, fuzzy, or grainy. This +is not a good experience for the user. Instead, use high-quality images. +</p> + +<p> +For more information on optimizing apps for large screens see <a href="{@docRoot}training/multiscreen/index.html"> +Designing for multiple screens</a>. +</p> + +<h2 id="HandleLargeBitmaps">Design to Handle Large Bitmaps</h2> + +<p> +The Android system has a limited amount of memory, so downloading and storing high-resolution images can often +cause out-of-memory errors in your app. To avoid this, follow these tips: +</p> + +<ul> + <li>Load images only when they're displayed on the screen. For example, when displaying multiple images in + a {@link android.widget.GridView} or + {@link android.widget.Gallery}, only load an image when + {@link android.widget.Adapter#getView(int, View, ViewGroup) getView()} + is called on the View's {@link android.widget.Adapter}. + </li> + <li>Call {@link android.graphics.Bitmap#recycle()} on + {@link android.graphics.Bitmap} views that are no longer needed. + </li> + <li>Use {@link java.lang.ref.WeakReference} for storing references + to {@link android.graphics.Bitmap} objects in a in-memory + <a href="{@link java.util.Collection}.</li> + <li>If you fetch images from the network, use {@link android.os.AsyncTask} + to fetch them and store them on the SD card for faster access. + Never do network transactions on the application's UI thread. + </li> + <li>Scale down really large images to a more appropriate size as you download them; otherwise, downloading the image + itself may cause an "Out of Memory" exception. Here is sample code that scales down images while downloading: + + <pre> + // Get the source image's dimensions + BitmapFactory.Options options = new BitmapFactory.Options(); + // This does not download the actual image, just downloads headers. + options.inJustDecodeBounds = true; + BitmapFactory.decodeFile(IMAGE_FILE_URL, options); + // The actual width of the image. + int srcWidth = options.outWidth; + // The actual height of the image. + int srcHeight = options.outHeight; + + // Only scale if the source is bigger than the width of the destination view. + if(desiredWidth > srcWidth) + desiredWidth = srcWidth; + + // Calculate the correct inSampleSize/scale value. This helps reduce memory use. It should be a power of 2. + int inSampleSize = 1; + while(srcWidth / 2 > desiredWidth){ + srcWidth /= 2; + srcHeight /= 2; + inSampleSize *= 2; + } + + float desiredScale = (float) desiredWidth / srcWidth; + + // Decode with inSampleSize + options.inJustDecodeBounds = false; + options.inDither = false; + options.inSampleSize = inSampleSize; + options.inScaled = false; + // Ensures the image stays as a 32-bit ARGB_8888 image. + // This preserves image quality. + options.inPreferredConfig = Bitmap.Config.ARGB_8888; + + Bitmap sampledSrcBitmap = BitmapFactory.decodeFile(IMAGE_FILE_URL, options); + + // Resize + Matrix matrix = new Matrix(); + matrix.postScale(desiredScale, desiredScale); + Bitmap scaledBitmap = Bitmap.createBitmap(sampledSrcBitmap, 0, 0, + sampledSrcBitmap.getWidth(), sampledSrcBitmap.getHeight(), matrix, true); + sampledSrcBitmap = null; + + // Save + FileOutputStream out = new FileOutputStream(LOCAL_PATH_TO_STORE_IMAGE); + scaledBitmap.compress(Bitmap.CompressFormat.JPEG, 100, out); + scaledBitmap = null; + </pre> + </li> </ul>
\ No newline at end of file diff --git a/docs/html/training/tv/optimizing-navigation-tv.jd b/docs/html/training/tv/optimizing-navigation-tv.jd new file mode 100644 index 0000000..8b5878e --- /dev/null +++ b/docs/html/training/tv/optimizing-navigation-tv.jd @@ -0,0 +1,206 @@ +page.title=Optimizing Navigation for TV +parent.title=Designing for TV +parent.link=index.html + +trainingnavtop=true +previous.title=Optimizing Layouts for TV +previous.link=optimizing-layouts-tv.html +next.title=Handling features not supported on TV +next.link=unsupported-features-tv.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#HandleDpadNavigation">Handle D-pad Navigation</a></li> + <li><a href="#HandleFocusSelection">Provide Clear Visual Indication for Focus and Selection</a></li> + <li><a href="#DesignForEasyNavigation">Design for Easy Navigation</a></li> +</ol> + +<h2>You should also read</h2> +<ul> + <li><a href="{@docRoot}training/design-navigation/index.html">Designing Effective Navigation</a></li> +</ul> + +</div> +</div> + +<p> +An important aspect of the user experience when operating a TV is the direct human interface: a remote control. +As you optimize your Android application for TVs, you should pay special attention to how the user actually navigates +around your application when using a remote control instead of a touchscreen. +</p> +<p> +This lesson shows you how to optimize navigation for TV by: +</p> + +<ul> + <li>Ensuring all layout controls are D-pad navigable.</li> + <li>Providing highly obvious feedback for UI navigation.</li> + <li>Placing layout controls for easy access.</li> +</ul> + +<h2 id="HandleDpadNavigation">Handle D-pad Navigation</h2> + +<p> +On a TV, users navigate with controls on a TV remote, using either a D-pad or arrow keys. +This limits movement to up, down, left, and right. +To build a great TV-optimized app, you must provide a navigation scheme in which the user can +quickly learn how to navigate your app using the remote. +</p> + +<p> +When you design navigation for D-pad, follow these guidelines: +</p> + +<ul> + <li>Ensure that the D-pad can navigate to all the visible controls on the screen.</li> + <li>For scrolling lists with focus, D-pad up/down keys scroll the list and Enter key selects an item in the list. Ensure that users can + select an element in the list and that the list still scrolls when an element is selected.</li> + <li>Ensure that movement between controls is straightforward and predictable.</li> +</ul> + +<p> +Android usually handles navigation order between layout elements automatically, so you don't need to do anything extra. If the screen layout +makes navigation difficult, or if you want users to move through the layout in a specific way, you can set up explicit navigation for your +controls. +For example, for an {@code android.widget.EditText}, to define the next control to receive focus, use: +<pre> +<EditText android:id="@+id/LastNameField" android:nextFocusDown="@+id/FirstNameField"\> +</pre> +The following table lists all of the available navigation attributes: +</p> + +<table> +<tr> +<th>Attribute</th> +<th>Function</th> +</tr> +<tr> +<td>{@link android.R.attr#nextFocusDown}</td> +<td>Defines the next view to receive focus when the user navigates down.</td> +</tr> +<tr> +<td>{@link android.R.attr#nextFocusLeft}</td> +<td>Defines the next view to receive focus when the user navigates left.</td> +</tr> +<tr> +<td>{@link android.R.attr#nextFocusRight}</td> +<td>Defines the next view to receive focus when the user navigates right.</td> +</tr> +<tr> +<td>{@link android.R.attr#nextFocusUp}</td> +<td>Defines the next view to receive focus when the user navigates up.</td> +</tr> +</table> + +<p> +To use one of these explicit navigation attributes, set the value to the ID (android:id value) of another widget in the layout. You should set +up the navigation order as a loop, so that the last control directs focus back to the first one. +</p> + +<p> +Note: You should only use these attributes to modify the navigation order if the default order that the system applies does not work well. +</p> + +<h2 id="HandleFocusSelection">Provide Clear Visual Indication for Focus and Selection</h2> + +<p> +Use appropriate color highlights for all navigable and selectable elements in the UI. This makes it easy for users to know whether the control +is currently focused or selected when they navigate with a D-pad. Also, use uniform highlight scheme across your application. +</p> + +<p> +Android provides <a href="{@docRoot}guide/topics/resources/drawable-resource.html#StateList">Drawable State List Resources</a> to implement highlights +for selected and focused controls. For example: +</p> + +res/drawable/button.xml: +<pre> +<?xml version="1.0" encoding="utf-8"?> +<selector xmlns:android="http://schemas.android.com/apk/res/android"> + <item android:state_pressed="true" + android:drawable="@drawable/button_pressed" /> <!-- pressed --> + <item android:state_focused="true" + android:drawable="@drawable/button_focused" /> <!-- focused --> + <item android:state_hovered="true" + android:drawable="@drawable/button_focused" /> <!-- hovered --> + <item android:drawable="@drawable/button_normal" /> <!-- default --> +</selector> +</pre> + +<p> +This layout XML applies the above state list drawable to a {@link android.widget.Button}: +</p> +<pre> +<Button + android:layout_height="wrap_content" + android:layout_width="wrap_content" + android:background="@drawable/button" /> +</pre> + +<p> +Provide sufficient padding within the focusable and selectable controls so that the highlights around them are clearly visible. +</p> + +<h2 id="DesignForEasyNavigation">Design for Easy Navigation</h2> + +<p> +Users should be able to navigate to any UI control with a couple of D-pad clicks. Navigation should be easy and intuitive to +understand. For any non-intuitive actions, provide users with written help, using a dialog triggered by a help button or action bar icon. +</p> + +<p> +Predict the next screen that the user will want to navigate to and provide one click navigation to it. If the current screen UI is very sparse, +consider making it a multi pane screen. Use fragments for making multi-pane screens. For example, consider the multi-pane UI below with continent names +on the left and list of cool places in each continent on the right. +</p> + +<img src="{@docRoot}images/training/cool-places.png" alt="" /> + +<p> +The above UI consists of three Fragments - <code>left_side_action_controls</code>, <code>continents</code> and +<code>places</code> - as shown in its layout +xml file below. Such multi-pane UIs make D-pad navigation easier and make good use of the horizontal screen space for +TVs. +</p> +res/layout/cool_places.xml +<pre> +<LinearLayout + android:layout_width="match_parent" + android:layout_height="match_parent" + android:orientation="horizontal" + > + <fragment + android:id="@+id/left_side_action_controls" + android:layout_width="0px" + android:layout_height="match_parent" + android:layout_marginLeft="10dip" + android:layout_weight="0.2"/> + <fragment + android:id="@+id/continents" + android:layout_width="0px" + android:layout_height="match_parent" + android:layout_marginLeft="10dip" + android:layout_weight="0.2"/> + + <fragment + android:id="@+id/places" + android:layout_width="0px" + android:layout_height="match_parent" + android:layout_marginLeft="10dip" + android:layout_weight="0.6"/> + +</LinearLayout> +</pre> + +<p> +Also, notice in the UI layout above action controls are on the left hand side of a vertically scrolling list to make +them easily accessible using D-pad. +In general, for layouts with horizontally scrolling components, place action controls on left or right hand side and +vice versa for vertically scrolling components. +</p> + diff --git a/docs/html/training/tv/unsupported-features-tv.jd b/docs/html/training/tv/unsupported-features-tv.jd new file mode 100644 index 0000000..6b0f8c8 --- /dev/null +++ b/docs/html/training/tv/unsupported-features-tv.jd @@ -0,0 +1,156 @@ +page.title=Handling Features Not Supported on TV +parent.title=Designing for TV +parent.link=index.html + +trainingnavtop=true +previous.title=Optimizing Navigation for TV +previous.link=optimizing-navigation-tv.html + +@jd:body + +<div id="tb-wrapper"> +<div id="tb"> + +<h2>This lesson teaches you to</h2> +<ol> + <li><a href="#WorkaroundUnsupportedFeatures">Work Around Features Not Supported on TV</a></li> + <li><a href="#CheckAvailableFeatures">Check for Available Features at Runtime</a></li> +</ol> + +</div> +</div> + +<p> +TVs are much different from other Android-powered devices: +</p> +<ul> + <li>They're not mobile.</li> + <li>Out of habit, people use them for watching media with little or no interaction.</li> + <li>People interact with them from a distance.</li> +</ul> + +<p> +Because TVs have a different purpose from other devices, they usually don't have hardware features +that other Android-powered devices often have. For this reason, the Android system does not +support the following features for a TV device: +<table> +<tr> +<th>Hardware</th> +<th>Android feature descriptor</th> +</tr> +<tr> +<td>Camera</td> +<td>android.hardware.camera</td> +</tr> +<tr> +<td>GPS</td> +<td>android.hardware.location.gps</td> +</tr> +<tr> +<td>Microphone</td> +<td>android.hardware.microphone</td> +</tr> +<tr> +<td>Near Field Communications (NFC)</td> +<td>android.hardware.nfc</td> +</tr> +<tr> +<td>Telephony</td> +<td>android.hardware.telephony</td> +</tr> +<tr> +<td>Touchscreen</td> +<td>android.hardware.touchscreen</td> +</tr> +</table> +</p> + +<p> +This lesson shows you how to work around features that are not available on TV by: +<ul> + <li>Providing work arounds for some non-supported features.</li> + <li>Checking for available features at runtime and conditionally activating/deactivating certain code + paths based on availability of those features.</li> +</ul> +</p> + + +<h2 id="WorkaroundUnsupportedFeatures">Work Around Features Not Supported on TV</h2> + +<p> +Android doesn't support touchscreen interaction for TV devices, most TVs don't have touch screens, +and interacting with a TV using a touchscreen is not consistent with the 10 foot environment. For +these reasons, users interact with Android-powered TVs using a remote. In consideration of this, +ensure that every control in your app can be accessed with the D-pad. Refer back to the previous two lessons +<a href="{@docRoot}training/tv/optimizing-layouts-tv">Optimizing Layouts for TV</a> and +<a href="{@docRoot}training/tv/optimizing-navigation-tv">Optimize Navigation for TV</a> for more details +on this topic. The Android system assumes that a device has a touchscreen, so if you want your application +to run on a TV, you must <strong>explicitly</strong> disable the touchscreen requirement in your manifest file: +<pre> +<uses-feature android:name="android.hardware.touchscreen" android:required="false"/> +</pre> +</p> + +<p> +Although a TV doesn't have a camera, you can still provide a photography-related application on a TV. +For example, if you have an app that takes, views and edits photos, you can disable its picture-taking +functionality for TVs and still allow users to view and even edit photos. The next section talks about how to +deactivate or activate specific functions in the application based on runtime device type detection. +</p> + +<p> +Because TVs are stationary, indoor devices, they don't have built-in GPS. If your application uses location +information, allow users to search for a location or use a "static" location provider to get +a location from the zip code configured during the TV setup. +<pre> +LocationManager locationManager = (LocationManager) this.getSystemService(Context.LOCATION_SERVICE); +Location location = locationManager.getLastKnownLocation("static"); +Geocoder geocoder = new Geocoder(this); +Address address = null; + +try { + address = geocoder.getFromLocation(location.getLatitude(), location.getLongitude(), 1).get(0); + Log.d("Zip code", address.getPostalCode()); + +} catch (IOException e) { + Log.e(TAG, "Geocoder error", e); +} +</pre> +</p> + +<p> +TVs usually don't support microphones, but if you have an application that uses voice control, +you can create a mobile device app that takes voice input and then acts as a remote control for a TV. +</p> + +<h2 id="CheckAvailableFeatures">Check for Available Features at Runtime</h2> + +<p> +To check if a feature is available at runtime, call +{@link android.content.pm.PackageManager#hasSystemFeature(String)}. + This method takes a single argument : a string corresponding to the +feature you want to check. For example, to check for touchscreen, use +{@link android.content.pm.PackageManager#hasSystemFeature(String)} with the argument +{@link android.content.pm.PackageManager#FEATURE_TOUCHSCREEN}. +</p> + +<p> +The following code snippet demonstrates how to detect device type at runtime based on supported features: + +<pre> +// Check if android.hardware.telephony feature is available. +if (getPackageManager().hasSystemFeature("android.hardware.telephony")) { + Log.d("Mobile Test", "Running on phone"); +// Check if android.hardware.touchscreen feature is available. +} else if (getPackageManager().hasSystemFeature("android.hardware.touchscreen")) { + Log.d("Tablet Test", "Running on devices that don't support telphony but have a touchscreen."); +} else { + Log.d("TV Test", "Running on a TV!"); +} +</pre> +</p> + +<p> +This is just one example of using runtime checks to deactivate app functionality that depends on features +that aren't available on TVs. +</p>
\ No newline at end of file |
