diff options
Diffstat (limited to 'docs')
139 files changed, 5317 insertions, 1104 deletions
diff --git a/docs/html/design/building-blocks/progress.jd b/docs/html/design/building-blocks/progress.jd index dc3ded1..b188538 100644 --- a/docs/html/design/building-blocks/progress.jd +++ b/docs/html/design/building-blocks/progress.jd @@ -42,9 +42,9 @@ available space.</p> <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 Google Play 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. +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> diff --git a/docs/html/design/building-blocks/tabs.jd b/docs/html/design/building-blocks/tabs.jd index 2c854d3..19ed1c3 100644 --- a/docs/html/design/building-blocks/tabs.jd +++ b/docs/html/design/building-blocks/tabs.jd @@ -25,7 +25,7 @@ to the next/previous view, swipe left or right.</p> <source src="{@docRoot}design/media/tabs_scrolly.ogv" type="video/ogg"> </video> <div class="figure-caption"> - Scrolling tabs in Google Play. + Scrolling tabs in the Play Store app. <div class="video-instructions"> </div> </div> diff --git a/docs/html/design/design_toc.cs b/docs/html/design/design_toc.cs index 19b58d9..6dd8d61 100644 --- a/docs/html/design/design_toc.cs +++ b/docs/html/design/design_toc.cs @@ -35,6 +35,7 @@ <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> diff --git a/docs/html/design/downloads/index.jd b/docs/html/design/downloads/index.jd index 618c44b..67dfd79 100644 --- a/docs/html/design/downloads/index.jd +++ b/docs/html/design/downloads/index.jd @@ -39,7 +39,7 @@ available.</p> <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_20120229.zip">Adobe® Photoshop® Sources</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> diff --git a/docs/html/design/get-started/principles.jd b/docs/html/design/get-started/principles.jd index 8f5b446..0b7147b 100644 --- a/docs/html/design/get-started/principles.jd +++ b/docs/html/design/get-started/principles.jd @@ -10,7 +10,7 @@ with purpose.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Delight me in surprising ways</h4> +<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> @@ -28,7 +28,7 @@ force is at hand.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Real objects are more fun than buttons and menus</h4> +<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> @@ -45,7 +45,7 @@ needed to perform a task while making it more emotionally satisfying.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Let me make it mine</h4> +<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> @@ -63,7 +63,7 @@ primary tasks.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Get to know me</h4> +<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> @@ -80,7 +80,7 @@ over, place previous choices within easy reach.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Keep it brief</h4> +<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> @@ -96,7 +96,7 @@ over, place previous choices within easy reach.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Pictures are faster than words</h4> +<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> @@ -113,7 +113,7 @@ than words.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Decide for me but let me have the final say</h4> +<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> @@ -130,7 +130,7 @@ unhappy. Just in case you get it wrong, allow for 'undo'.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Only show what I need when I need it</h4> +<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> @@ -147,7 +147,7 @@ digestible chunks. Hide options that aren't essential at the moment, and teach p <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>I should always know where I am</h4> +<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> @@ -164,7 +164,7 @@ use transitions to show relationships among screens. Provide feedback on tasks i <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Never lose my stuff</h4> +<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> @@ -182,7 +182,7 @@ easiest thing in the world.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>If it looks the same, it should act the same</h4> +<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> @@ -199,7 +199,7 @@ Avoid modes, which are places that look similar but act differently on the same <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Only interrupt me if it's important</h4> +<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> @@ -216,7 +216,7 @@ focused, and unless it's critical and time-sensitive, an interruption can be tax <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Give me tricks that work everywhere</h4> +<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> @@ -234,7 +234,7 @@ may be a good navigational shortcut.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>It's not my fault</h4> +<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> @@ -252,7 +252,7 @@ If you can fix it behind the scenes, even better.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Sprinkle encouragement</h4> +<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> @@ -269,7 +269,7 @@ even if it's just a subtle glow.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Do the heavy lifting for me</h4> +<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> @@ -287,7 +287,7 @@ only a few steps.</p> <div class="layout-content-row"> <div class="layout-content-col span-7"> -<h4>Make important things fast</h4> +<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> diff --git a/docs/html/design/media/app_structure_market.png b/docs/html/design/media/app_structure_market.png Binary files differindex 3b0b786..5aa595e 100644 --- a/docs/html/design/media/app_structure_market.png +++ 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 differindex 0dd400c..67354de 100644 --- a/docs/html/design/media/app_structure_music_lndscp.png +++ b/docs/html/design/media/app_structure_music_lndscp.png diff --git a/docs/html/design/media/app_structure_scrolltabs.png b/docs/html/design/media/app_structure_scrolltabs.png Binary files differindex ef4fca4..ea742c2 100644 --- a/docs/html/design/media/app_structure_scrolltabs.png +++ 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 differindex 3874e1d4..1341f1f 100644 --- a/docs/html/design/media/app_structure_shortcut_on_item.png +++ b/docs/html/design/media/app_structure_shortcut_on_item.png diff --git a/docs/html/design/media/iconography_launcher_example.png b/docs/html/design/media/iconography_launcher_example.png Binary files differindex a5db53e..0cce7ef 100644 --- a/docs/html/design/media/iconography_launcher_example.png +++ b/docs/html/design/media/iconography_launcher_example.png diff --git a/docs/html/design/media/iconography_overview.png b/docs/html/design/media/iconography_overview.png Binary files differindex 688c1b5..56cd409 100644 --- a/docs/html/design/media/iconography_overview.png +++ b/docs/html/design/media/iconography_overview.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/media/misc_full_galaxynexus_blank_land_span13.png b/docs/html/design/media/misc_full_galaxynexus_blank_land_span13.png Binary files differdeleted file mode 100644 index bab6aca..0000000 --- a/docs/html/design/media/misc_full_galaxynexus_blank_land_span13.png +++ /dev/null diff --git a/docs/html/design/media/misc_full_galaxynexus_blank_port_span5.png b/docs/html/design/media/misc_full_galaxynexus_blank_port_span5.png Binary files differdeleted file mode 100644 index bdccc2f..0000000 --- a/docs/html/design/media/misc_full_galaxynexus_blank_port_span5.png +++ /dev/null diff --git a/docs/html/design/media/misc_full_galaxynexus_blank_port_span9.png b/docs/html/design/media/misc_full_galaxynexus_blank_port_span9.png Binary files differdeleted file mode 100644 index 5e0135b..0000000 --- a/docs/html/design/media/misc_full_galaxynexus_blank_port_span9.png +++ /dev/null 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/media/navigation_between_siblings_market1.png b/docs/html/design/media/navigation_between_siblings_market1.png Binary files differindex c3148f8..8f2b3dc 100644..100755 --- a/docs/html/design/media/navigation_between_siblings_market1.png +++ b/docs/html/design/media/navigation_between_siblings_market1.png diff --git a/docs/html/design/media/navigation_between_siblings_market2.png b/docs/html/design/media/navigation_between_siblings_market2.png Binary files differindex 208be47..33b654c 100644..100755 --- a/docs/html/design/media/navigation_between_siblings_market2.png +++ b/docs/html/design/media/navigation_between_siblings_market2.png diff --git a/docs/html/design/media/navigation_from_outside_up.png b/docs/html/design/media/navigation_from_outside_up.png Binary files differdeleted file mode 100644 index eaa3cdb..0000000 --- a/docs/html/design/media/navigation_from_outside_up.png +++ /dev/null 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 differindex 71e6484..ff7adfe 100644 --- a/docs/html/design/media/navigation_up_vs_back_gmail.png +++ 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 differindex 4fb6dce..5440220 100644 --- a/docs/html/design/media/navigation_with_back_and_up.png +++ b/docs/html/design/media/navigation_with_back_and_up.png diff --git a/docs/html/design/media/progress_activity.png b/docs/html/design/media/progress_activity.png Binary files differindex 51210b4..32cf1f5 100644 --- a/docs/html/design/media/progress_activity.png +++ b/docs/html/design/media/progress_activity.png diff --git a/docs/html/design/media/progress_download.png b/docs/html/design/media/progress_download.png Binary files differindex f567f74..ab6bf58 100644 --- a/docs/html/design/media/progress_download.png +++ b/docs/html/design/media/progress_download.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/media/tabs_scrolly.mp4 b/docs/html/design/media/tabs_scrolly.mp4 Binary files differindex 4329243..dc9e9c6 100644 --- a/docs/html/design/media/tabs_scrolly.mp4 +++ 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 differindex 345e57a..3e484f9 100644 --- a/docs/html/design/media/tabs_scrolly.ogv +++ 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 differindex 17e368e..e9d371d 100644 --- a/docs/html/design/media/tabs_scrolly.webm +++ b/docs/html/design/media/tabs_scrolly.webm diff --git a/docs/html/design/media/ui_overview_all_apps.png b/docs/html/design/media/ui_overview_all_apps.png Binary files differindex 467f5ad..17e7ece 100644 --- a/docs/html/design/media/ui_overview_all_apps.png +++ b/docs/html/design/media/ui_overview_all_apps.png diff --git a/docs/html/design/patterns/actionbar.jd b/docs/html/design/patterns/actionbar.jd index 9e3f48c..2226fec 100644 --- a/docs/html/design/patterns/actionbar.jd +++ b/docs/html/design/patterns/actionbar.jd @@ -176,7 +176,7 @@ themselves.</p> <source src="{@docRoot}design/media/tabs_scrolly.ogv" type="video/ogg"> </video> <div class="figure-caption"> - Scrolling tabs in Google Play. + Scrolling tabs in the Play Store app. <div class="video-instructions"> </div> </div> diff --git a/docs/html/design/patterns/app-structure.jd b/docs/html/design/patterns/app-structure.jd index b54b12f..e2398ed 100644 --- a/docs/html/design/patterns/app-structure.jd +++ b/docs/html/design/patterns/app-structure.jd @@ -7,7 +7,7 @@ page.title=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 Google Play 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 id="general-structure">General Structure</h2> @@ -60,7 +60,7 @@ layouts that are visually engaging and appropriate for the data type and screen <img src="{@docRoot}design/media/app_structure_market.png"> <div class="figure-caption"> - The Google Play app'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> @@ -145,8 +145,8 @@ minimize navigational effort. Rule of thumb: no more than 5–7 tabs.</p> <img src="{@docRoot}design/media/app_structure_scrolltabs.png"> <div class="figure-caption"> - Google Play 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> diff --git a/docs/html/design/patterns/navigation.jd b/docs/html/design/patterns/navigation.jd index d35cd82..7e288ae 100644 --- a/docs/html/design/patterns/navigation.jd +++ b/docs/html/design/patterns/navigation.jd @@ -13,32 +13,36 @@ the <em>Up</em> button, consisting of the app icon and a left-point caret.</p> <h2 id="up-vs-back">Up vs. Back</h2> -<p>The Up button is used to navigate within an application based on the hierarchical relationships +<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 (i.e. the home of the app), it should not present an Up +<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 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>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 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> +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 key also supports a few behaviors not directly tied to screen-to-screen navigation:</p> +<p>The Back button 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> +<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—e.g., a settings screen which can be navigated to from any screen +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> @@ -50,7 +54,7 @@ in the same place within the app's hierarchy, and no new navigation history is c <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> +<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 @@ -61,56 +65,140 @@ 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 on Google Play between apps from +<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 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> +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. If we extend our Google Play 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> +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="from-outside">Navigation From Outside Your App</h2> +<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> -<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> +<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>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 on Google Play, 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 -Google Play.</p> - -<img src="{@docRoot}design/media/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> + +<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/pure-android.jd b/docs/html/design/patterns/pure-android.jd index 8ed1347..77813c0 100644 --- a/docs/html/design/patterns/pure-android.jd +++ b/docs/html/design/patterns/pure-android.jd @@ -48,7 +48,8 @@ conventions of a different platform.</p> 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> +<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"> @@ -89,6 +90,33 @@ platform and to avoid confusion between actions and view switching on Android.</ <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 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/style/writing.jd b/docs/html/design/style/writing.jd index 80fd03e..919ea7a 100644 --- a/docs/html/design/style/writing.jd +++ b/docs/html/design/style/writing.jd @@ -1,58 +1,6 @@ page.title=Writing Style @jd:body -<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({@docRoot}assets/design/ico_wrong.png); -} - -.example_label.good { - background-image: url({@docRoot}assets/design/ico_good.png); -} - -</style> - <p>When choosing words for your app:</p> <ol> <li> @@ -90,20 +38,20 @@ page.title=Writing Style <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="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">Too formal</div> + <div class="do-dont-label bad">Too formal</div> - <table class="ui_table good"><tbody><tr><td> + <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> + <div class="do-dont-label good">Better</div> - <table class="ui_table good"><tbody><tr><td> + <table class="ui-table good"><tbody><tr><td> Read the instructions that came with your phone. </td></tr></tbody></table> @@ -115,11 +63,11 @@ page.title=Writing Style <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="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">Confusing</div> + <div class="do-dont-label bad">Confusing</div> - <table class="ui_table bad"> + <table class="ui-table bad"> <thead> <tr> <th> @@ -139,9 +87,9 @@ page.title=Writing Style </div> <div class="layout-content-col span-6"> - <div class="example_label good">Better</div> + <div class="do-dont-label good">Better</div> - <table class="ui_table good"> + <table class="ui-table good"> <thead> <tr> <th> @@ -167,12 +115,12 @@ page.title=Writing Style crashes:</ol> <div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">Confusing and annoying—"Sorry" just rubs salt in the + <div class="do-dont-label bad">Confusing and annoying—"Sorry" just rubs salt in the wound.</div> - <table class="ui_table bad"> + <table class="ui-table bad"> <thead> <tr> <th colspan="3"> @@ -200,9 +148,9 @@ crashes:</ol> </div> <div class="layout-content-col span-6"> - <div class="example_label good">Shorter, more direct, no faux-apologetic title:<br><br></div> + <div class="do-dont-label good">Shorter, more direct, no faux-apologetic title:<br><br></div> - <table class="ui_table good"> + <table class="ui-table good"> <thead> <tr> <th colspan="3"> @@ -234,20 +182,20 @@ crashes:</ol> <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="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">Top news last</div> + <div class="do-dont-label bad">Top news last</div> - <table class="ui_table bad"><tbody><tr><td> + <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> + <div class="do-dont-label good">Top news first</div> - <table class="ui_table good"><tbody><tr><td> + <table class="ui-table good"><tbody><tr><td> Larry Page and 77 others +1'd this. </td></tr></tbody></table> @@ -255,20 +203,20 @@ crashes:</ol> </div> <div class="layout-content-row"> - <div class="layout-content-col span-6 list_item_margins"> + <div class="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">Task last</div> + <div class="do-dont-label bad">Task last</div> - <table class="ui_table bad"><tbody><tr><td> + <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> + <div class="do-dont-label good">Task first</div> - <table class="ui_table good"><tbody><tr><td> + <table class="ui-table good"><tbody><tr><td> To finish setup using Wi-Fi, touch Next. </td></tr></tbody></table> @@ -280,11 +228,11 @@ crashes:</ol> <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="layout-content-col span-6 layout-with-list-item-margins"> - <div class="example_label bad">From a Setup Wizard screen</div> + <div class="do-dont-label bad">From a Setup Wizard screen</div> - <table class="ui_table bad"> + <table class="ui-table bad"> <thead> <tr> <th> @@ -306,9 +254,9 @@ crashes:</ol> </div> <div class="layout-content-col span-6"> - <div class="example_label good">From a Setup Wizard screen</div> + <div class="do-dont-label good">From a Setup Wizard screen</div> - <table class="ui_table good"> + <table class="ui-table good"> <thead> <tr> <th> 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/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/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/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/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/guide_toc.cs b/docs/html/guide/guide_toc.cs index 9d5064e..ba8dc5e 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"> @@ -502,8 +512,7 @@ <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></a> - <span class="new">new!</span> + <span class="en">APK Expansion Files<span class="new"> new!</span></span></a> </li> </ul> </li> @@ -788,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> @@ -835,9 +844,6 @@ applications</span> </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/market/billing/billing_integrate.jd b/docs/html/guide/market/billing/billing_integrate.jd index b49dc25..4b3650f 100755 --- a/docs/html/guide/market/billing/billing_integrate.jd +++ b/docs/html/guide/market/billing/billing_integrate.jd @@ -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> diff --git a/docs/html/guide/market/licensing/overview.jd b/docs/html/guide/market/licensing/overview.jd index 05a3a40..e7e23f8 100644 --- a/docs/html/guide/market/licensing/overview.jd +++ b/docs/html/guide/market/licensing/overview.jd @@ -58,8 +58,9 @@ information about the application and user—your application and the Google 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 +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 @@ -116,7 +117,7 @@ tampered with or that are spoofed.</p> <h2 id="LVL">Licensing Verification Library</h2> -<p>The Android SDK provides a downloadable component called the "Google Market Licensing package," +<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 @@ -162,8 +163,8 @@ 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 component of the Android SDK. The -component includes both the LVL itself and an example application that shows how +<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> diff --git a/docs/html/guide/market/licensing/setting-up.jd b/docs/html/guide/market/licensing/setting-up.jd index 41e3bc4..0de7819 100644 --- a/docs/html/guide/market/licensing/setting-up.jd +++ b/docs/html/guide/market/licensing/setting-up.jd @@ -173,25 +173,25 @@ 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 add-on are available through the SDK Manager, but only -<strong>Google APIs Add-On, API 8 (release 2) or higher</strong> includes the necessary Google +<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. </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. - <p>When the download is complete, use the Android SDK 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 Manager, click + <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 "Google APIs (Google Inc.) - API Level 8" as +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 @@ -238,8 +238,8 @@ 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> +<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> @@ -248,9 +248,9 @@ 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 +<p>To download the LVL package into your development environment, use the Android SDK Manager. Launch the Android SDK Manager and then -select the "Google Market Licensing" component, as shown in figure 2. +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=""/> @@ -265,8 +265,8 @@ the LVL library project and the example application into these directories: </p> <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> +<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> @@ -676,7 +676,7 @@ credentials. </p> <ol> <li>Open Settings > Accounts & sync</li> -<li>Select <strong>Add Account</strong> and choose to add a "Google" account. +<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 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 72da04e..0000000 --- a/docs/html/guide/practices/design/accessibility.jd +++ /dev/null @@ -1,352 +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://play.google.com/store/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 the <a -href="https://play.google.com/store/details?id=com.google.android.marvin.talkback">Google Play</a> store.</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 140c50c..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> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 29dff26..a870b22 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -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/publishing/app-signing.jd b/docs/html/guide/publishing/app-signing.jd index e86ec30..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> @@ -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> @@ -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/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/uses-feature-element.jd b/docs/html/guide/topics/manifest/uses-feature-element.jd index 9175566..5f0a501 100644 --- a/docs/html/guide/topics/manifest/uses-feature-element.jd +++ b/docs/html/guide/topics/manifest/uses-feature-element.jd @@ -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> 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..ff34be6 --- /dev/null +++ b/docs/html/guide/topics/ui/accessibility/apps.jd @@ -0,0 +1,570 @@ +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">Note: 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 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 the +arrow keys and Enter key on your keyboard with the Emulator 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/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/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/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/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 787a655..d3203bb 100644 --- a/docs/html/index.jd +++ b/docs/html/index.jd @@ -53,28 +53,32 @@ Android apps!</p> <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://play.google.com/apps/publish"><img src="{@docRoot}assets/images/icon_play.png" 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>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> + <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> 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/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/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/dashboard/opengl.jd b/docs/html/resources/dashboard/opengl.jd index b1c3234..4c55522 100644 --- a/docs/html/resources/dashboard/opengl.jd +++ b/docs/html/resources/dashboard/opengl.jd @@ -57,7 +57,7 @@ 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.8,89.2" /> +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.8%</td> +<td>11.9%</td> </tr> <tr> <td>2.0 & 1.1</th> -<td>89.2%</td> +<td>88.1%</td> </tr> </table> -<p><em>Data collected during a 7-day period ending on March 4, 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 65a5575..2cbbe99 100644 --- a/docs/html/resources/dashboard/platform-versions.jd +++ b/docs/html/resources/dashboard/platform-versions.jd @@ -52,7 +52,7 @@ Google Play within a 14-day period ending on the data collection date noted belo <div class="dashboard-panel"> <img alt="" height="250" width="470" -src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:0.4,0.8,6.6,25.2,0.5,61.4,0.1,1.1,2.1,0.4,1.2&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.4,0.8,6.6,25. <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.4%</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.8%</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.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>25.3%</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>61.5%</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.1%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-3.2.html">Android 3.2</a></td><!-- Honeycomb --><td>13</td><td>2.1%</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.4%</td></tr> -<tr><td><a href="{@docRoot}sdk/android-4.0.3.html">Android 4.0.3</a></td><!-- ICS --><td>15</td><td>1.2%</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 March 5, 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> --> @@ -108,9 +108,9 @@ Google Play within a 14-day period ending on the date indicated on the x-axis.</ <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%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C01/15%7C02/01%7C02/15%7C03/01%7C1%3A%7C2011%7C%7C%7C%7C%7C%7C%7C%7C2012%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.9,97.9,97.7,97.6,97.5,99.4,99.4,99.2,98.9,98.8,99.2,98.9,98.9|96.9,96.9,96.6,96.6,96.5,98.6,98.6,98.5,98.3,98.2,98.6,98.4,98.4|95.1,95.2,95.1,95.4,95.2,97.2,97.3,97.3,97.2,97.2,97.6,97.5,97.6|81.8,82.7,83.3,84.4,84.6,87.0,87.7,88.1,88.7,89.2,89.9,90.3,90.8|30.6,34.1,37.8,40.8,43.5,48.4,52.4,55.2,58.2,60.1,62.0,63.7,65.2|0.0,0.0,0.0,0.0,0.0,2.0,2.3,2.6,3.5,3.6,4.0,4.1,4.3|0.0,0.0,0.0,0.0,0.0,1.0,1.2,1.3,2.0,2.2,2.6,3.0,3.2|0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.3,0.4,0.7,0.8,1.1&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" /> +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 March 5, 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 e9c738e..e5c79a1 100644 --- a/docs/html/resources/dashboard/screens.jd +++ b/docs/html/resources/dashboard/screens.jd @@ -60,7 +60,7 @@ 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.9,0.2,2.8,66.4,0.7,18.5,2.5,2.4,1.7" /> +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.7%</td> <!-- small/ldpi --> +<td>1.9%</td> <!-- small/ldpi --> <td></td> <!-- small/mdpi --> -<td>2.4%</td> <!-- small/hdpi --> +<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.5%</td> <!-- normal/mdpi --> -<td>66.3%</td> <!-- normal/hdpi --> -<td>2.5%</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.8%</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.9%</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 March 4, 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 e1a5e0f..bbbe6fb 100644 --- a/docs/html/resources/resources_toc.cs +++ b/docs/html/resources/resources_toc.cs @@ -97,11 +97,36 @@ </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> - </a> <span class="new">new!</span> + <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"> @@ -253,7 +278,44 @@ </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/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/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/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-3.0.jd b/docs/html/sdk/android-3.0.jd index 39a234f..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> diff --git a/docs/html/sdk/android-4.0.3.jd b/docs/html/sdk/android-4.0.3.jd index c8563ac..f6dbee0 100644 --- a/docs/html/sdk/android-4.0.3.jd +++ b/docs/html/sdk/android-4.0.3.jd @@ -68,6 +68,28 @@ 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="" /> + Revision 3</a> <em>(March 2012)</em> + </a></p> + + <div class="toggle-content-toggleme" style="padding-left:2em;"> + + <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> + +<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 2</a> <em>(January 2012)</em> </a></p> diff --git a/docs/html/sdk/compatibility-library.jd b/docs/html/sdk/compatibility-library.jd index 30d807f..f81e8ae 100644 --- a/docs/html/sdk/compatibility-library.jd +++ b/docs/html/sdk/compatibility-library.jd @@ -330,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 3019544..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=17.0.0 -adt.zip.download=ADT-17.0.0.zip -adt.zip.bytes=12836115 -adt.zip.checksum=ecb12c07e534997cd32c66d57f21b770 +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> @@ -108,10 +108,45 @@ 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" /> +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> @@ -468,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> @@ -520,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> @@ -656,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> @@ -686,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> @@ -736,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> @@ -845,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> @@ -874,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> @@ -1020,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> @@ -1038,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> @@ -1087,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> @@ -1114,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> @@ -1318,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> @@ -1345,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 c09b3c2..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_r17-windows.exe -sdk.win_installer_bytes=37410775 -sdk.win_installer_checksum=5afaf6511ebaa52bd6d1dba4afc61e41 +sdk.win_installer=installer_r18-windows.exe +sdk.win_installer_bytes=37456234 +sdk.win_installer_checksum=48b1fe7b431afe6b9c8a992bf75dd898 -sdk.win_download=android-sdk_r17-windows.zip -sdk.win_bytes=37417953 -sdk.win_checksum=3af1baeb39707e54df068e939aea5a79 +sdk.win_download=android-sdk_r18-windows.zip +sdk.win_bytes=37448775 +sdk.win_checksum=bfbfdf8b2d0fdecc2a621544d706fa98 -sdk.mac_download=android-sdk_r17-macosx.zip -sdk.mac_bytes=33867836 -sdk.mac_checksum=52639aae036b7c2e47cf291696b23236 +sdk.mac_download=android-sdk_r18-macosx.zip +sdk.mac_bytes=33903758 +sdk.mac_checksum=8328e8a5531c9d6f6f1a0261cb97af36 -sdk.linux_download=android-sdk_r17-linux.tgz -sdk.linux_bytes=29706368 -sdk.linux_checksum=14e99dfa8eb1a8fadd2f3557322245c4 +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=14e99dfa8eb1a8fadd2f3557322245c4 <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 a1c59e3..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"> diff --git a/docs/html/sdk/oem-usb.jd b/docs/html/sdk/oem-usb.jd index 818a0af..88d66dd 100644 --- a/docs/html/sdk/oem-usb.jd +++ b/docs/html/sdk/oem-usb.jd @@ -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/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs index 5a5517c..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,10 +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> @@ -153,11 +151,9 @@ class="new">new!</span></li> </li> </ul> <ul> - <li><a href="<?cs var:toroot ?>sdk/tools-notes.html">SDK Tools, r17</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, r7</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> @@ -172,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 17.0.0 + <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> @@ -196,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 dea0c38..f4e9d4d 100644 --- a/docs/html/sdk/tools-notes.jd +++ b/docs/html/sdk/tools-notes.jd @@ -68,6 +68,48 @@ padding: .25em 1em; <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"> @@ -96,12 +138,13 @@ padding: .25em 1em; <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>) - <p class="note"><strong>Note:</strong> As of the SDK Tools Revision 17 release, the -API Level 15, Revision 3 system image is not yet available.</p> </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>)</li> +(<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> diff --git a/docs/html/sdk/win-usb.jd b/docs/html/sdk/win-usb.jd index 6869d74..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) { @@ -149,7 +149,7 @@ for the T-Mobile G1 and myTouch 3G (and similar devices).</p></dt> <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/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/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..d5178a9 --- /dev/null +++ b/docs/html/training/accessibility/index.jd @@ -0,0 +1,56 @@ +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> +Playback</a></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/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/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/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 |
