Merge "docs: update uses-feature doc with USB features, add TOC at the top and revise some other stuff" into honeycomb-mr1
diff --git a/core/res/res/values-de/strings.xml b/core/res/res/values-de/strings.xml
index db3e9d9..69496ac 100644
--- a/core/res/res/values-de/strings.xml
+++ b/core/res/res/values-de/strings.xml
@@ -151,7 +151,7 @@
<string name="global_actions_toggle_airplane_mode" msgid="5884330306926307456">"Flugmodus"</string>
<string name="global_actions_airplane_mode_on_status" msgid="2719557982608919750">"Flugmodus ist AN."</string>
<string name="global_actions_airplane_mode_off_status" msgid="5075070442854490296">"Flugmodus ist AUS."</string>
- <string name="status_bar_notification_info_overflow" msgid="5833510281787786290">"100 +"</string>
+ <string name="status_bar_notification_info_overflow" msgid="5833510281787786290">"Mehr als 100"</string>
<string name="safeMode" msgid="2788228061547930246">"Abgesicherter Modus"</string>
<string name="android_system_label" msgid="6577375335728551336">"Android-System"</string>
<string name="permgrouplab_costMoney" msgid="5429808217861460401">"Kostenpflichtige Dienste"</string>
@@ -161,7 +161,7 @@
<string name="permgrouplab_personalInfo" msgid="3519163141070533474">"Ihre persönlichen Informationen"</string>
<string name="permgroupdesc_personalInfo" product="tablet" msgid="6975389054186265786">"Direkter Zugriff auf die Kontakte und den Kalender Ihres Tablets"</string>
<string name="permgroupdesc_personalInfo" product="default" msgid="5488050357388806068">"Direkter Zugriff auf die Kontakte und den Kalender Ihres Telefons"</string>
- <string name="permgrouplab_location" msgid="635149742436692049">"Ihren Standort"</string>
+ <string name="permgrouplab_location" msgid="635149742436692049">"Meinen Standort"</string>
<string name="permgroupdesc_location" msgid="2430258821648348660">"Ihren physischen Standort überwachen"</string>
<string name="permgrouplab_network" msgid="5808983377727109831">"Netzwerkkommunikation"</string>
<string name="permgroupdesc_network" msgid="5035763698958415998">"Ermöglicht Anwendungen den Zugriff auf verschiedene Netzwerkfunktionen"</string>
@@ -465,7 +465,7 @@
<string name="permdesc_sdcardWrite" product="nosdcard" msgid="6594393334785738252">"Ermöglicht der Anwendung Schreiben in USB-Speicher"</string>
<string name="permdesc_sdcardWrite" product="default" msgid="6643963204976471878">"Ermöglicht einer Anwendung, auf die SD-Karte zu schreiben"</string>
<string name="permlab_mediaStorageWrite" product="default" msgid="6859839199706879015">"Intern. Mediensp. änd./löschen"</string>
- <string name="permdesc_mediaStorageWrite" product="default" msgid="8232008512478316233">"Ermöglicht es einer Anwendung, den Inhalt des internen Medienspeichers zu ändern"</string>
+ <string name="permdesc_mediaStorageWrite" product="default" msgid="8232008512478316233">"Ermöglicht einer Anwendung, den Inhalt des internen Medienspeichers zu ändern"</string>
<string name="permlab_cache_filesystem" msgid="5656487264819669824">"Zugriff auf das Cache-Dateisystem"</string>
<string name="permdesc_cache_filesystem" msgid="1624734528435659906">"Gewährt einer Anwendung Lese- und Schreibzugriff auf das Cache-Dateisystem."</string>
<string name="permlab_use_sip" msgid="5986952362795870502">"Internetanrufe tätigen/annehmen"</string>
@@ -966,7 +966,7 @@
<string name="l2tp_ipsec_psk_vpn_description" msgid="3945043564008303239">"L2TP/IPSec-VPN mit vorinstalliertem Schlüssel"</string>
<string name="l2tp_ipsec_crt_vpn_description" msgid="5382714073103653577">"L2TP/IPSec-VPN mit Zertifikat"</string>
<string name="upload_file" msgid="2897957172366730416">"Datei auswählen"</string>
- <string name="no_file_chosen" msgid="6363648562170759465">"Keine Datei ausgewählt"</string>
+ <string name="no_file_chosen" msgid="6363648562170759465">"Keine ausgewählt"</string>
<string name="reset" msgid="2448168080964209908">"Zurücksetzen"</string>
<string name="submit" msgid="1602335572089911941">"Senden"</string>
<string name="car_mode_disable_notification_title" msgid="3164768212003864316">"Automodus aktiviert"</string>
diff --git a/core/res/res/values-ko/strings.xml b/core/res/res/values-ko/strings.xml
index 1b7051e..2b48934 100644
--- a/core/res/res/values-ko/strings.xml
+++ b/core/res/res/values-ko/strings.xml
@@ -949,7 +949,7 @@
<string name="create_contact_using" msgid="4947405226788104538">"전화번호부에"\n"<xliff:g id="NUMBER">%s</xliff:g> 추가"</string>
<string name="accessibility_compound_button_selected" msgid="5612776946036285686">"선택함"</string>
<string name="accessibility_compound_button_unselected" msgid="8864512895673924091">"선택 안함"</string>
- <string name="grant_credentials_permission_message_header" msgid="6824538733852821001">"현재 이후로 하나 이상의 다음 애플리케이션이 계정에 대한 액세스 권한을 요청합니다."</string>
+ <string name="grant_credentials_permission_message_header" msgid="6824538733852821001">"다음 애플리케이션에서 계정 액세스 요청이 들어왔습니다."</string>
<string name="grant_credentials_permission_message_footer" msgid="3125211343379376561">"요청을 허용하시겠습니까?"</string>
<string name="grant_permissions_header_text" msgid="2722567482180797717">"액세스 요청"</string>
<string name="allow" msgid="7225948811296386551">"허용"</string>
diff --git a/core/res/res/values-zh-rTW/strings.xml b/core/res/res/values-zh-rTW/strings.xml
index f87c2f6..c8cf46d 100644
--- a/core/res/res/values-zh-rTW/strings.xml
+++ b/core/res/res/values-zh-rTW/strings.xml
@@ -68,7 +68,7 @@
<string name="serviceNotProvisioned" msgid="8614830180508686666">"無法提供此服務。"</string>
<string name="CLIRPermanent" msgid="5460892159398802465">"本機號碼顯示設定無法變更。"</string>
<string name="RestrictedChangedTitle" msgid="5592189398956187498">"受限存取已變更"</string>
- <string name="RestrictedOnData" msgid="8653794784690065540">"已封鎖資料傳輸服務。"</string>
+ <string name="RestrictedOnData" msgid="8653794784690065540">"已封鎖數據傳輸服務。"</string>
<string name="RestrictedOnEmergency" msgid="6581163779072833665">"已封鎖緊急服務。"</string>
<string name="RestrictedOnNormal" msgid="4953867011389750673">"已封鎖語音服務。"</string>
<string name="RestrictedOnAllVoice" msgid="1459318899842232234">"已封鎖所有語音服務。"</string>
@@ -696,15 +696,15 @@
<string name="beforeOneMonthDurationPast" msgid="909134546836499826">"1 個月前"</string>
<plurals name="num_seconds_ago">
<item quantity="one" msgid="4869870056547896011">"1 秒以前"</item>
- <item quantity="other" msgid="3903706804349556379">"<xliff:g id="COUNT">%d</xliff:g> 秒以前"</item>
+ <item quantity="other" msgid="3903706804349556379">"<xliff:g id="COUNT">%d</xliff:g> 秒前"</item>
</plurals>
<plurals name="num_minutes_ago">
<item quantity="one" msgid="3306787433088810191">"1 分鐘以前"</item>
- <item quantity="other" msgid="2176942008915455116">"<xliff:g id="COUNT">%d</xliff:g> 分鐘以前"</item>
+ <item quantity="other" msgid="2176942008915455116">"<xliff:g id="COUNT">%d</xliff:g> 分鐘前"</item>
</plurals>
<plurals name="num_hours_ago">
<item quantity="one" msgid="9150797944610821849">"1 小時以前"</item>
- <item quantity="other" msgid="2467273239587587569">"<xliff:g id="COUNT">%d</xliff:g> 小時以前"</item>
+ <item quantity="other" msgid="2467273239587587569">"<xliff:g id="COUNT">%d</xliff:g> 小時前"</item>
</plurals>
<plurals name="last_num_days">
<item quantity="other" msgid="3069992808164318268">"最近 <xliff:g id="COUNT">%d</xliff:g> 天"</item>
@@ -713,7 +713,7 @@
<string name="older" msgid="5211975022815554840">"較舊"</string>
<plurals name="num_days_ago">
<item quantity="one" msgid="861358534398115820">"昨天"</item>
- <item quantity="other" msgid="2479586466153314633">"<xliff:g id="COUNT">%d</xliff:g> 天以前"</item>
+ <item quantity="other" msgid="2479586466153314633">"<xliff:g id="COUNT">%d</xliff:g> 天前"</item>
</plurals>
<plurals name="in_num_seconds">
<item quantity="one" msgid="2729745560954905102">"1 秒內"</item>
@@ -741,11 +741,11 @@
</plurals>
<plurals name="abbrev_num_hours_ago">
<item quantity="one" msgid="4796212039724722116">"1 小時以前"</item>
- <item quantity="other" msgid="6889970745748538901">"<xliff:g id="COUNT">%d</xliff:g> 小時以前"</item>
+ <item quantity="other" msgid="6889970745748538901">"<xliff:g id="COUNT">%d</xliff:g> 小時前"</item>
</plurals>
<plurals name="abbrev_num_days_ago">
<item quantity="one" msgid="8463161711492680309">"昨天"</item>
- <item quantity="other" msgid="3453342639616481191">"<xliff:g id="COUNT">%d</xliff:g> 天以前"</item>
+ <item quantity="other" msgid="3453342639616481191">"<xliff:g id="COUNT">%d</xliff:g> 天前"</item>
</plurals>
<plurals name="abbrev_in_num_seconds">
<item quantity="one" msgid="5842225370795066299">"1 秒內"</item>
@@ -918,14 +918,14 @@
<string name="ext_media_unmountable_notification_title" product="nosdcard" msgid="2090046769532713563">"USB 儲存裝置已毀損"</string>
<string name="ext_media_unmountable_notification_title" product="default" msgid="6410723906019100189">"SD 卡已損壞"</string>
<string name="ext_media_unmountable_notification_message" product="nosdcard" msgid="529021299294450667">"USB 儲存裝置已損壞，您可能必須重新格式化。"</string>
- <string name="ext_media_unmountable_notification_message" product="default" msgid="6902531775948238989">"SD 卡已毀損，您可能必須予以重新格式化。"</string>
- <string name="ext_media_badremoval_notification_title" product="nosdcard" msgid="1661683031330951073">"USB 儲存裝置已意外移除"</string>
+ <string name="ext_media_unmountable_notification_message" product="default" msgid="6902531775948238989">"SD 卡已毀損，您可能必須重新格式化。"</string>
+ <string name="ext_media_badremoval_notification_title" product="nosdcard" msgid="1661683031330951073">"USB 儲存裝置未正常移除"</string>
<string name="ext_media_badremoval_notification_title" product="default" msgid="6872152882604407837">"SD 卡未正常移除"</string>
<string name="ext_media_badremoval_notification_message" product="nosdcard" msgid="4329848819865594241">"請先卸載 USB 儲存裝置，再將其移除，以免資料遺失。"</string>
<string name="ext_media_badremoval_notification_message" product="default" msgid="7260183293747448241">"請先卸載 SD 卡，再將其移除，以免資料遺失。"</string>
<string name="ext_media_safe_unmount_notification_title" product="nosdcard" msgid="3967973893270360230">"USB 儲存裝置已可安全移除"</string>
<string name="ext_media_safe_unmount_notification_title" product="default" msgid="6729801130790616200">"可安全移除 SD 卡"</string>
- <string name="ext_media_safe_unmount_notification_message" product="nosdcard" msgid="6142195361606493530">"您可安全移除 USB 儲存裝置了。"</string>
+ <string name="ext_media_safe_unmount_notification_message" product="nosdcard" msgid="6142195361606493530">"您現在可以安全地移除 USB 儲存裝置。"</string>
<string name="ext_media_safe_unmount_notification_message" product="default" msgid="568841278138377604">"您現在可以安全地移除 SD 卡。"</string>
<string name="ext_media_nomedia_notification_title" product="nosdcard" msgid="4486377230140227651">"USB 儲存裝置已移除"</string>
<string name="ext_media_nomedia_notification_title" product="default" msgid="8902518030404381318">"已移除 SD 卡"</string>
diff --git a/docs/html/guide/appendix/api-levels.jd b/docs/html/guide/appendix/api-levels.jd
index 013cc94..5c18a83 100644
--- a/docs/html/guide/appendix/api-levels.jd
+++ b/docs/html/guide/appendix/api-levels.jd
@@ -83,8 +83,10 @@
<table>
<tr><th>Platform Version</th><th>API Level</th></tr>
+ <tr><td>Android 3.1</td><td>12</td></tr>
<tr><td>Android 3.0</td><td>11</td></tr>
- <tr><td>Android 2.3.3</td><td>10</td></tr>
+ <tr><td>Android 2.3.4</td><td rowspan="2">10</td></tr>
+ <tr><td>Android 2.3.3</td></tr>
<tr><td>Android 2.3</td><td>9</td></tr>
<tr><td>Android 2.2</td><td>8</td></tr>
<tr><td>Android 2.1</td><td>7</td></tr>
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 35acdd7..916da09 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -304,6 +304,7 @@
<ul>
<li><a href="<?cs var:toroot ?>guide/topics/usb/accessory.html">Accessory</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/usb/host.html">Host</a></li>
+ <li><a href="<?cs var:toroot ?>guide/topics/usb/adk.html">Open Accessory Dev Kit</a></li>
</ul>
</li>
@@ -652,9 +653,19 @@
<li><a href="<?cs var:toroot ?>guide/practices/compatibility.html">
<span class="en">Compatibility</span>
</a></li>
- <li><a href="<?cs var:toroot ?>guide/practices/screens_support.html">
- <span class="en">Supporting Multiple Screens</span>
+ <li class="toggle-list">
+ <div><a href="<?cs var:toroot ?>guide/practices/screens_support.html">
+ <span class="en">Supporting Multiple Screens</span>
+ </a></div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>guide/practices/screens-distribution.html">
+ <span class="en">Distributing to Specific Screens</span>
</a></li>
+ <li><a href="<?cs var:toroot ?>guide/practices/screens-support-1.5.html">
+ <span class="en">Strategies for Android 1.5</span>
+ </a></li>
+ </ul>
+ </li>
<li><a href="<?cs var:toroot ?>guide/practices/optimizing-for-3.0.html">
<span class="en">Optimizing Apps for Android 3.0</span>
</a></li>
diff --git a/docs/html/guide/practices/screens-distribution.jd b/docs/html/guide/practices/screens-distribution.jd
new file mode 100644
index 0000000..0c5193b
--- /dev/null
+++ b/docs/html/guide/practices/screens-distribution.jd
@@ -0,0 +1,164 @@
+page.title=Distributing to Specific Screens
+parent.title=Supporting Multiple Screens
+parent.link=screens_support.html
+
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+ <h2>Quickview</h2>
+ <ul>
+ <li>If necessary, you can control distribution of your application based on the device
+screen configuration</li>
+ </ul>
+
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#FilteringHansetApps">Filtering a Handset Application from Tablets</a></li>
+ <li><a href="#FilteringTabletApps">Filtering a Tablet Application from Handsets</a></li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
+ <li><a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+ <li><a
+href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing Apps for Android 3.0</a></li>
+ </ol>
+
+</div>
+</div>
+
+
+
+<p>Although we recommend that you design your application to function properly on multiple
+configurations of screen size and density, you can instead choose to limit the distribution of your
+application to certain types of screens, such as only tablets and other large devices or only
+handsets and similar-sized devices. To do so, you can enable filtering by external services such as
+Android Market by adding elements to your manifest file that specify the screen configurations your
+application supports.</p>
+
+<p>However, before you decide to restrict your application to certain screen configurations, you
+should understand the techniques for <a
+href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and implement
+them to the best of your ability. By supporting multiple screens, your application can be made
+available to the greatest number of users with different devices, using a single {@code .apk}.</p>
+
+
+
+<h2 id="FilteringHandsetApps">Filtering a Handset Application from Tablets</h2>
+
+<p>Because the system generally scales applications to fit larger screens well, you shouldn't
+need to filter your application from larger screens. As long as you follow the <a
+href="{@docRoot}guide/practices/screens_support.html#screen-independence">Best Practices for Screen
+Independence</a>, your application should work well on larger screens such as tablets. However, you
+might discover that your application can't scale up well or perhaps you've decided to publish two
+versions of your application for different screen configurations. In such a case, you can use the <a
+href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
+<compatible-screens>}</a> element to manage the distribution of your application based on
+combinations of screen size and density. External services such as Android Market use this
+information to apply filtering to your application, so that only devices that have a screen
+configuration with which you declare compatibility can download your application.</p>
+
+<p>The <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
+<compatible-screens>}</a> element must contain one or more {@code <screen>} elements. Each
+{@code <screen>} element specifies a screen configuration with which your application is
+compatible, using both the {@code android:screenSize} and {@code android:screenDensity} attributes.
+Each {@code <screen>} element <strong>must include both attributes</strong> to specify an
+individual screen configuration—if either attribute is missing, then the element is invalid
+(external services such as Android Market will ignore it).</p>
+
+<p>For example, if your application is compatible with only small and normal size screens,
+regardless of screen density, you must specify eight different {@code <screen>} elements,
+because each screen size has four density configurations. You must declare each one of
+these; any combination of size and density that you do <em>not</em> specify is considered a screen
+configuration with which your application is <em>not</em> compatible. Here's what the manifest
+entry looks like if your application is compatible with only small and normal screen sizes:</p>
+
+<pre>
+<manifest ... >
+ ...
+ <compatible-screens>
+ <!-- all small size screens -->
+ <screen android:screenSize="small" android:screenDensity="ldpi" />
+ <screen android:screenSize="small" android:screenDensity="mdpi" />
+ <screen android:screenSize="small" android:screenDensity="hdpi" />
+ <screen android:screenSize="small" android:screenDensity="xhdpi" />
+ <!-- all normal size screens -->
+ <screen android:screenSize="normal" android:screenDensity="ldpi" />
+ <screen android:screenSize="normal" android:screenDensity="mdpi" />
+ <screen android:screenSize="normal" android:screenDensity="hdpi" />
+ <screen android:screenSize="normal" android:screenDensity="xhdpi" />
+ </compatible-screens>
+ <application ... >
+ ...
+ <application>
+</manifest>
+</pre>
+
+<p class="note"><strong>Note:</strong> Although you can also use the <a
+href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
+<compatible-screens>}</a> element for the reverse scenario (when your application is not
+compatible with smaller screens), it's easier if you instead use the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> as discussed in the next section, because it doesn't require you
+to specify each screen density your application supports.</p>
+
+
+
+<h2 id="FilteringTabletApps">Filtering a Tablet Application from Handsets</h2>
+
+<p>If your application's UI is adversely affected when the system scales your application down to
+smaller screens, you should add <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
+layouts</a> for smaller screens to adjust the layout for those screens. However, sometimes your
+layout still might not fit a smaller screen or you've explicitly designed your application only for
+tablets and other large devices. In this case, you can manage the availability of your application
+to smaller screens by using the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> manifest element.</p>
+
+<p>For example, if you want your application to be available only to large and extra large
+screens, you can declare the element in your manifest like this:</p>
+
+<pre>
+<manifest ... >
+ ...
+ <supports-screens android:smallScreens="false"
+ android:normalScreens="false"
+ android:largeScreens="true"
+ android:xlargeScreens="true" />
+ <application ... >
+ ...
+ <application>
+</manifest>
+</pre>
+
+<p>External services such as Android Market read this manifest element and use it to ensure that
+your application is available only to devices with either a large or an extra large screen.</p>
+
+<p class="caution"><strong>Caution:</strong> If you use the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> element for the reverse scenario (when your application is not compatible
+with <em>larger</em> screens) and set the larger screen size attributes to {@code "false"}, then
+external services such as Android Market <strong>do not</strong> apply filtering. Your application
+will still be available to larger screens, but when it runs, it will not resize to fit the screen.
+Instead, the system will draw it in a "postage stamp" window that's the same relative size as the
+screen size that your application does support (see <a
+href="screens-support-1.5.html#CompatMode">compatibility mode</a> for more information). If you want
+to prevent your application from being downloaded on larger screens, use <a
+href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
+<compatible-screens>}</a>, as discussed in the previous section about <a
+href="#FilteringHandsetApps">Filtering a Handset Application from Tablets</a>.</p>
+
+<p>Remember, you should strive to make your application available to as many devices as possible by
+applying all necessary techniques for <a
+href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a>. You should
+use <a href="{@docRoot}guide/topics/manifest/compatible-screens-element.html">{@code
+<compatible-screens>}</a> or <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> only when you cannot provide compatibility on all screen configurations
+or you have decided to provide different versions of your application for different sets of screen
+configurations.</p>
+
diff --git a/docs/html/guide/practices/screens-support-1.5.jd b/docs/html/guide/practices/screens-support-1.5.jd
new file mode 100644
index 0000000..6fd36bb
--- /dev/null
+++ b/docs/html/guide/practices/screens-support-1.5.jd
@@ -0,0 +1,186 @@
+page.title=Strategies for Android 1.5
+parent.title=Supporting Multiple Screens
+parent.link=screens_support.html
+
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+ <h2>Quickview</h2>
+ <ul>
+ <li>Apps developed for Android 1.5 and below support only the baseline screen
+configuration, by default</li>
+ <li>There are some simple steps you should take to enable support for multiple screens in
+an application designed for Android 1.5</li>
+ </ul>
+
+ <h2>In this document</h2>
+ <ol>
+ <li><a href="#strategies">Adding Multiple Screens Support</a></li>
+ <li><a href="#CompatMode">Compatibility Mode</a></li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
+ <li><a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a></li>
+ </ol>
+
+</div>
+</div>
+
+
+<p>All applications written for Android 1.5 or earlier, by default, support only the
+baseline HVGA screen used on the T-Mobile G1 and similar devices, which is <em>normal</em> screen
+size and medium density (<em>mdpi</em>). Android 1.6 introduced support for different screen
+configurations and added APIs that allow applications to control how they operate on different
+screens, using alternative resources for different screen configurations.</p>
+
+<p>If your manifest file includes the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element,
+with the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
+attribute set to {@code "3"} or lower, and does <em>not</em> include the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> set to {@code "4"} or higher, then this document is for you. By
+default, an application written for Android 1.5 or below that does not set the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> set to {@code "4"} or higher runs in <a
+href="#CompatMode">compatibility mode</a> when on a device with a screen larger than the
+<em>normal</em> screen size (basically, the system displays the application in a small window
+that is roughly the size of the normal screen size).</p>
+
+<p>This document describes how to get your application out of <a href="#CompatMode">compatibility
+mode</a> and instead support multiple screens, but also maintain compatibility with Android 1.5 and
+below.</p>
+
+<p class="note"><strong>Note:</strong> Before you begin, you should first decide whether it's even
+necessary to support Android 1.5. To see the relative number of devices that are still running
+Android 1.5, see the <a
+href="http://developer.android.com/resources/dashboard/platform-versions.html">Platform Versions
+Dashboard</a>.</p>
+
+
+
+
+<h2 id="strategies">Adding Multiple Screens Support</h2>
+
+<p>If you have already developed and published an Android application based on
+Android 1.5 or earlier platform version, and want to maintain compatibility with Android 1.5, you
+need to make some changes to your application in order for it to properly run on newer devices with
+different screen configurations. You should be able to make these changes to your application such
+that you can distribute a single {@code .apk} to all devices.</p>
+
+<p>The recommended strategy is to develop your application against Android 1.6 (because it's the
+lowest version that includes support for multiple screens) and test your application on each
+platform version your application supports (especially the minimum platform, such as Android 1.5).
+Here's how to do that:</p>
+
+<ol>
+ <li>Maintain compatibility with existing devices by leaving your application's <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
+attribute as it is. You <em>do not</em> need to increment the value of the attribute to support new
+devices and multiple screens. </li>
+ <li>Extend compatibility for Android 1.6 (and higher) devices by adding <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> to the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> element.
+Set the value of <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> to <code>"4"</code>. This allows your application to "inherit" the
+platform's multiple screens support, even though it is technically using an earlier version of the
+API.
+ <p>Adding this attribute will cause an error in the compiler, because the attribute is unknown to
+Android 1.5. You'll fix this next.</p></li>
+ <li>Change your application's build properties, such that it compiles against the Android 1.6 (API
+Level 4) library, rather than against the Android 1.5 (or earlier) library. You must do this in
+order for your application to successfully compile when using the new manifest attributes. Older
+versions of the platform simply ignore the attributes they don't know, so your application still
+runs fine on them, as long as you don't use APIs in your application code from Android 1.6. </li>
+</ol>
+
+<p>Your application is now prepared to run on multiple screens, while maintaining support for
+Android 1.5 or lower.</p>
+
+<p>Here's how you should begin testing your application:</p>
+
+<ol>
+ <li>Set up AVDs for testing your application on Android 1.6 and some new versions. Create AVDs
+that use the screen sizes and densities that you want to support. When you create the AVDs, make
+sure to select the Android 1.6 or higher platform as the system image to use. For more information,
+see <a href="{@docRoot}guide/practices/screens_support.html#testing">How to Test Your Application on
+Multiple Screens</a>.</li>
+ <li>Set up AVDs for testing your application on older versions of the platform, as low as the
+version declared by your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>.
+You need AVDs running the older platforms you are targeting, so that you can ensure there are
+no functional regressions.</li>
+ <li>Compile your application against the Android 1.6 library and run it on the AVDs you created.
+Observe the way your application looks and runs, and test all of the user interactions.</li>
+ <li>Debug any display or functional issues. For issues that you resolve in
+your application code, <span style="color:red">make certain not to use any APIs
+introduced later than the version declared by your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+android:minSdkVersion}</a></span>. If you
+are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API
+you want to use. Using newer APIs not supported by your minimum version will mean that your
+application will no longer be compatible with devices running on that version.</li>
+</ol>
+
+<p>In particular, remember to test your application on an AVD that emulates a small-screen device.
+Users of devices with QVGA resolution at low density may want to download your application, so you
+should understand how your application will look and function on a small-screen device. In some
+cases, the reduced screen area and density mean that you need to make tradeoffs in design on those
+devices.</p>
+
+<p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em>
+screen. Devices with extra large screens are tablet-sized or larger, so you should pay close
+attention to how usable your application is on such screens. You might want to design new layouts
+specifically for extra large screens, to address usability aspects such as the location and size of
+buttons in your UI. To test your application on an extra large screen, create an AVD targeted to
+Android 3.0 and use the WXGA emulator skin.</p>
+
+<p>Once you've completed the procedures above, you should follow the recommendations in <a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> to add
+complete support for different screen configurations.</p>
+
+
+<h2 id="CompatMode">Compatibility Mode</h2>
+
+<div class="figure" style="width:450px;margin:0">
+<img src="{@docRoot}images/screens_support/compat-mode-on.png" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> An application running in compatibility mode
+on an extra large screen.</p>
+</div>
+
+<p>To allow applications to run on larger screens without stretching the UI, Android provides a
+compatibility mode that draws an application's UI in a "postage stamp" window when on larger
+screens. That is, the system displays the application at the baseline size (<em>normal</em>) and
+density (<em>mdpi</em>), with a black border that fills the rest of the screen.</p>
+
+<p>Compatibility mode exists primarily to support application's developed for Android 1.5 (or lower)
+when running on larger screens, because multiple screen support was not added until Android 1.6,
+older applications were not designed to support different screen configurations.</p>
+
+<p>As such, if you've set your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+android:minSdkVersion}</a> to {@code "3"} or lower and have <em>not</em> set the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> to {@code "4"} or higher, then compatibility mode is enabled and
+the system will not scale your application, because your application implicitly declares that it
+only supports the baseline screen configuration (normal screen size and medium density).</p>
+
+<p>To disable compatibility mode, set either <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code
+android:minSdkVersion}</a> or <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+android:targetSdkVersion}</a> to {@code "4"} or higher. For more information, see the previous
+section about <a href="#strategies">Adding Multiple Screens Support</a>.</p>
+
+<p>You can also affect whether compatibility mode is enabled by using the <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
+<supports-screens>}</a> element (you can enable it by setting {@code android:resizeable} or
+specific screen sizes to {@code "false"}). However, you should not explicitly enable compatibility
+mode for your application, but should instead apply the necessary techniques to <a
+href="{@docRoot}guide/practices/screens_support.html">supporting multiple screens</a> and allow your
+application to properly fit the screen on all screen sizes.</p>
diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd
index 9875a6e..14de152 100644
--- a/docs/html/guide/practices/screens_support.jd
+++ b/docs/html/guide/practices/screens_support.jd
@@ -1,5 +1,4 @@
page.title=Supporting Multiple Screens
-
@jd:body
<div id="qv-wrapper">
@@ -7,772 +6,359 @@
<h2>Quickview</h2>
<ul>
- <li>Android runs on devices that have different screen sizes and resolutions.</li>
+ <li>Android runs on devices that have different screen sizes and densities.</li>
<li>The screen on which your application is displayed can affect its user interface.</li>
- <li>The platform handles most of the work of adapting your app to the current screen.</li>
- <li>You can create screen-specific resources for precise control of your UI, if needed. </li>
- <li>Older applications run in a compatibility mode that provides best-effort rendering on the current screen.</li>
- <li>It's important to follow the best practices described in this document and test your application in all supported screens. </li>
+ <li>The system handles most of the work of adapting your app to the current screen.</li>
+ <li>You should create screen-specific resources for precise control of your UI. </li>
</ul>
<h2>In this document</h2>
<ol>
- <li><a href="#overview">Overview of Screen Support</a></li>
- <ol>
- <li><a href="#range">Range of screens supported</a></li>
- <li><a href="#support">How Android supports multiple screens</a></li>
- <li><a href="#density-independence">Density independence</a></li>
- <li><a href="#attrs">Manifest attributes</a></li>
- <li><a href="#qualifiers">Resource qualifiers</a></li>
- </ol>
- <li style="padding-top:4px;"><a href="#screen-independence">Best Practices for Screen Independence</a></li>
- <li><a href="#strategies">Strategies for Legacy Apps</a></li>
- <li><a href="#testing">How to Test Your App</a></li>
-
+ <li><a href="#overview">Overview of Screen Support</a>
+ <ol>
+ <li><a href="#terms">Terms and concepts</a></li>
+ <li><a href="#range">Range of screens supported</a></li>
+ <li><a href="#density-independence">Density independence</a></li>
+ </ol></li>
+ <li><a href="#support">How to Support Multiple Screens</a>
+ <ol>
+ <li><a href="#qualifiers">Using configuration qualifiers</a></li>
+ <li><a href="#DesigningResources">Designing alternative layouts and drawables</a></li>
+ </ol></li>
+ <li><a href="#screen-independence">Best Practices</a></li>
+ <li><a href="#DensityConsiderations">Additional Density Considerations</a>
+ <ol>
+ <li><a href="#scaling">Scaling Bitmap objects created at runtime</a></li>
+ <li><a href="#dips-pels">Converting dp units to pixel units</a></li>
+ </ol></li>
+ <li><a href="#testing">How to Test Your Application on Multiple Screens</a></li>
</ol>
- <h2>See Also</h2>
+ <h2>Related samples</h2>
<ol>
- <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li>
- <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li>
+ <li><a href="{@docRoot}resources/samples/MultiResolution/index.html">Multiple
+Resolutions</a></li>
+ </ol>
+
+ <h2>See also</h2>
+ <ol>
<li><a
href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a></li>
- <li><a href="{@docRoot}guide/developing/devices/index.html">Creating and Managing Virtual Devices</a></li>
+ <li><a href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design
+Guidelines</a></li>
+ <li><a href="{@docRoot}guide/developing/devices/index.html">Managing Virtual Devices</a></li>
</ol>
</div>
</div>
-<p>Android is designed to run on a variety of devices that offer a range of
-screen sizes and resolutions. For applications, the platform provides a
-consistent environment across devices and handles much of the complexity of
-adapting an application's UI to the screen on which it is being displayed. At
-the same time, the platform exposes APIs that give application developers
-precise control over their application's UI when displayed on specific screen
-sizes and resolutions. </p>
+<p>Android runs on a variety of devices that offer different screen sizes and densities. For
+applications, the Android system provides a consistent development environment across devices and
+handles most of the work to adjust each application's user interface to the screen on which it is
+displayed. At the same time, the system provides APIs that allow you to control your
+application's UI on specific screen sizes and densities, in order to modify and optimize your UI
+design for different screen configurations. For example, you might want a UI for tablets
+that's different from the design for handsets.</p>
-<p>This document explains the screens-support features provided by the platform
-and how you use them in your application. By following the practices described
-here, you can easily create an application that displays properly on all
-supported device screens and that you can deploy to any device as a single {@code .apk}.
-</p>
+<p>Although the system performs sufficient scaling and resizing to make your application work on
+different screens, you should make the effort to optimize your application for different screen
+sizes and densities. In doing so, you maximize the user experience for all devices and your users
+believe that your application was actually designed for <em>their</em> devices—rather than
+simply stretched to fit their devices.</p>
-<p>If you have already developed and published an application for Android 1.5 or
-earlier, you should read this document and consider how you may need to adapt
-your application for proper display on new devices that offer different screens
-and that are running Android 1.6 or later. In most cases, only minor adjustments
-are needed, however you should make sure to <a href="#testing">test your
-application</a> on all supported screens. </p>
+<p>By following the practices described in this document, you can create an application that
+displays properly and provides an optimized user experience on all supported screen configurations,
+using a single {@code .apk} file.</p>
-<p>Starting in Android 2.2, the platform includes support for extra high density screens
-(<em>xhdpi</em>), and starting in Android 2.3, the platform includes support for extra large screens
-(<em>xlarge</em>). If you've already followed the guidance in this document to support all other
-screen types, you should consider providing additional support for <em>xhdpi</em> and
-<em>xlarge</em> screens.</p>
+<p class="note"><strong>Note:</strong> The information in this document assumes that your
+application is designed for Android 1.6 (API Level 4) or higher. If your application supports
+Android 1.5 or lower, please first read <a
+href="{@docRoot}guide/practices/screens-support-1.5.html">Strategies for Android 1.5</a>.</p>
-<p>In particular, if you have an existing application that you would like to
-make available on small screens (such as QVGA) or for which you would like to provide better support
-for extra large screens, please see <a href="#strategies">Strategies for Legacy Applications</a> for
-more information about how to do that. </p>
<h2 id="overview">Overview of Screens Support</h2>
-<p>The sections below provide an overview of the Android platform's support for
-multiple screens, including an introduction to terms and concepts used in this
-document and in the API, a summary of the screen configurations that the
-platform supports, and an overview of the API and underlying
+<p>This section provides an overview of Android's support for multiple screens, including: an
+introduction to the terms and concepts used in this document and in the API, a summary of the screen
+configurations that the system supports, and an overview of the API and underlying
screen-compatibility features.</p>
-
-<h3>Terms and Concepts</h3>
+<h3 id="terms">Terms and concepts</h3>
<dl>
<dt><em>Screen size</em></dt>
<dd>Actual physical size, measured as the screen's diagonal.
- <p>For simplicity, Android collapses all actual screen sizes into four
-generalized sizes: small, normal, large, and extra large. Applications can provide custom
-layouts for each of these four sizes — the platform transparently handles
-the rendering of the layouts at the actual screen size.</p></dd>
+ <p>For simplicity, Android groups all actual screen sizes into four generalized sizes: small,
+normal, large, and extra large.</p></dd>
-<dt><em>Aspect ratio</em></dt>
- <dd>The porportional relationship of the screen's physical width to its
-height. Applications can provide layout resources for specific aspect ratios by
-using the resource qualifiers <code>long</code> and <code>notlong</code>. </dd>
+<dt><em>Screen density</em></dt>
+ <dd>The quantity of pixels within a physical area of the screen; usually referred to as dpi (dots
+per inch). For example, a "low" density screen has fewer pixels within a given physical area,
+compared to a "normal" or "high" density screen.</p>
+
+ <p>For simplicity, Android groups all actual screen densities into four generalized densities:
+low, medium, high, and extra high.</p></dd>
+
+<dt><em>Orientation</em></dt>
+ <dd>The orientation of the screen from the user's point of view. This is either landscape or
+portrait, meaning that the screen's aspect ratio is either wide or tall, respectively. Be aware
+that not only do different devices operate in different orientations by default, but the
+orientation can change at runtime when the user rotates the device.
+</dd>
<dt><em>Resolution</em></dt>
- <dd>The total number of physical pixels on a screen. Note that, although
-resolution is often expressed as <em>width</em> x <em>height</em>, resolution
-does not imply a specific aspect ratio. In Android, applications do not work
-directly with resolution.</dd>
+ <dd>The total number of physical pixels on a screen. When adding support for multiple screens,
+applications do not work directly with resolution; applications should be concerned only with screen
+size and density, as specified by the generalized size and density groups.</dd>
-<dt><em>Density</em></dt>
- <dd>Based on the screen resolution, the spread of pixels across the physical
-width and height of the screen.
-
- <p>A screen with lower density has fewer available pixels spread across the
-screen width and height, where a screen with higher density has more —
-sometimes significantly more — pixels spread across the same area. The
-density of a screen is important because, other things being equal, a UI element
-(such as a button) whose height and width are defined in terms of screen pixels
-will appear larger on the lower density screen and smaller on the higher density
-screen.</p>
-
- <p>For simplicity, Android collapses all actual screen densities into four
-generalized densities: low, medium, large, and extra large. Applications can provide custom
-resources for each of these densities — the platform handles any necessary
-scaling of the resources up or down to meet the specific screen density. </p></dd>
<dt><em>Density-independent pixel (dp)</em></dt>
- <dd>A virtual pixel unit that applications can use in defining their UI, to
-express layout dimensions or position in a density-independent way.
- <p>The density-independent pixel is equivalent to one physical pixel on a 160
-dpi screen, the baseline density assumed by the platform (as described later in
-this document). At run time, the platform transparently handles any scaling of
-the dp units needed, based on the actual density of the screen in use. The
-conversion of dp units to screen pixels is simple: <nobr><code>pixels = dps *
-(density / 160)</code></nobr>. For example, on 240 dpi screen, 1 dp would equal 1.5
-physical pixels. Using dp units to define your application's UI is highly
-recommended, as a way of ensuring proper display of your UI on different
-screens. </p></dd>
+ <dd>A virtual pixel unit that you should use when defining UI layout, to express layout dimensions
+or position in a density-independent way.
+ <p>The density-independent pixel is equivalent to one physical pixel on a 160 dpi screen, which is
+the baseline density assumed by the system for a "medium" density screen. At runtime, the system
+transparently handles any scaling of the dp units, as necessary, based on the actual density of the
+screen in use. The conversion of dp units to screen pixels is simple:
+<nobr><code>px = dp * (dpi / 160)</code></nobr>.
+For example, on a 240 dpi screen, 1 dp equals 1.5 physical pixels. You should always use dp units
+when defining your application's UI, to ensure proper display of your UI on screens with different
+densities. </p></dd>
</dl>
<h3 id="range">Range of screens supported</h3>
-<p>Starting from Android 1.6, the platform provides support for multiple screen
-sizes and resolutions, reflecting the many new types and sizes of devices on
-which the platform runs. If you are developing an application that will run
-on Android 1.6 or later, you can use the compatibility features of the Android
-platform to ensure that your application UI renders properly across the range of
-supported screen sizes and resolutions.</p>
+<p>Starting with Android 1.6 (API Level 4), Android provides support for multiple screen sizes and
+densities, reflecting the many different screen configurations that a device may have. You can use
+features of the Android system to optimize your application's user interface for each screen
+configuration and ensure that your application not only renders properly, but provides the best
+user experience possible on each screen.</p>
-<p>To simplify the way that developers design their user interfaces for
-multiple devices and to allow more devices to participate without affecting
-applications, the platform divides the range of actual supported screen sizes
-and resolutions into:</p>
+<p>To simplify the way that you design your user interfaces for multiple screens, Android divides
+the range of actual screen sizes and densities into:</p>
<ul>
-<li>A set of four generalized sizes: <em>small</em>, <em>normal</em>, <em>large</em>,
+<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>,
+<em>large</em>,
and <em>xlarge</em></em>
-<li>A set of four generalized densities: <em>ldpi</em> (low), <em>mdpi</em> (medium),
+<li>A set of four generalized <strong>densities</strong>: <em>ldpi</em> (low), <em>mdpi</em>
+(medium),
<em>hdpi</em> (high), and <em>xhdpi</em> (extra high)
</ul>
-<p class="note"><strong>Note:</strong> The <code>xhdpi</code> density category was added in
-Android 2.2 (API Level 8). The <em>xlarge</em> size category was added in Android 2.3 (API Level
-9).</p>
+<p>The generalized sizes and densities are arranged around a
+baseline configuration that is a <em>normal</em> size and <em>mdpi</em> (medium) density. This
+baseline is based upon the screen configuration for the first Android-powered device, the T-Mobile
+G1, which has an HVGA screen (until Android 1.6, this was the only screen configuration that Android
+supported).</p>
-<p>Applications can provide custom resources (primarily layouts) for any of the
-four generalized sizes and can provide resources (primarily drawables such as
-images) for any of the four generalized densities. Applications do not need to
-work with the actual physical size or density of the device screen. At run time,
-the platform handles the loading of the correct size or density resources, based
-on the generalized size or density of the current device screen, and adapts them
-to the actual pixel map of the screen.</p>
+<p>Each generalized size or density spans a range of actual screen sizes or density. For example,
+two devices that both report a screen size of <em>normal</em> might have actual screen sizes and
+aspect ratios that are slightly different when measured by hand. Similarly, two devices that report
+a screen density of <em>hdpi</em> might have real pixel densities that are slightly different.
+Android makes these differences abstract to applications, so you can provide UI designed for the
+generalized sizes and densities and let the system handle any final adjustments as necessary. Figure
+1 illustrates how different sizes and densities are roughly categorized into the different size
+and density groups.</p>
-<p>The generalized size/density configurations are arranged around a
-baseline configuration that is assigned a size of <em>normal</em> and a density of
-<em>mdpi</em> (medium). All applications written for Android 1.5 or earlier are (by
-definition) designed for the baseline HVGA screen used on the T-Mobile G1 and
-similar devices, which is size <em>normal</em> and density
-<em>mdpi</em>.</p>
-
-<p>Each generalized screen configuration spans a range of actual screen
-densities and physical sizes. For example, that means that multiple devices that
-report a screen size of <em>normal</em> might offer screens that differ slightly
-in actual size or aspect ratio. Similarly, devices that report a screen density
-of <em>hdpi</em> might offer screens with slightly different pixel densities.
-The platform makes these differences abstract, however — applications can
-offer UI designed for the generalized sizes and densities and let the system
-handle the actual rendering of the UI on the current device screen according to
-its characteristics. </p>
-
-<img src="{@docRoot}images/screens_support/screens-ranges.png" />
+<img src="{@docRoot}images/screens_support/screens-ranges.png" style="padding:1em 0 0" alt="" />
<p class="img-caption"><strong>Figure 1.</strong>
-Illustration of how the Android platform maps actual screen densities and sizes
-to generalized density and size configurations. </p>
+Illustration of how Android roughly maps actual sizes and densities
+to generalized sizes and densities (figures are not exact).</p>
-<p>Layout designs often need to be done against a minimum amount of
-available space, so each screen size bucket has an associated minimum size.
-These sizes are in "dp" units -- the same units you should use in defining
-your layouts, which allow us to avoid worrying about changes in screen density.</p>
+<p>To optimize your application's UI for the different screen sizes and densities, you can provide
+<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">alternative
+resources</a> for any of the generalized sizes and densities. Typically, you should
+provide alternative layouts for some of the different screen sizes and alternative bitmap images for
+different screen densities. At runtime, the system uses the appropriate size or density resources
+for your application, based on the generalized size or density of the current device screen.</p>
-<ul>
-<li> <em>xlarge</em> screens are at least 960dp x 720dp.
-<li> <em>large</em> screens are at least 640dp x 480dp.
-<li> <em>normal</em> screens are at least 470dp x 320dp.
-<li> <em>small</em> screens are at least 426dp x 320dp.
-</ul>
+<p>You do not need to provide alternative resources for every combination of screen size and
+density. The system provides robust compatibility features that can handle most of the work of
+rendering your application on any device screen, provided that you've implemented your UI using
+techniques that allow it to gracefully resize (as described in the <a
+href="#screen-independence">Best Practices</a>, below).</p>
-<p>Note that these minimum screen sizes were not
-as well defined prior to Android 3.0, so you may encounter some devices
-that are mis-classified between normal and large. These are also based
-on the physical resolution of the screen, so may vary across devices --
-for example a 1024x720 tablet with a system bar would actually have a bit
-less space available to the application due to it being used by the system
-bar. Android does not currently support screens smaller than the "small"
-426dp x 320dp size.</p>
+<p class="note"><strong>Note:</strong> The characteristics that define a device's generalized screen
+size and density are independent from each other. For example, a WVGA high-density screen is
+considered a normal size screen because its physical size is about the same as the T-Mobile G1
+(Android's first device and baseline screen configuration). On the other hand, a WVGA medium-density
+screen is considered a large size screen. Although it offers the same resolution (the same number of
+pixels), the WVGA medium-density screen has a lower screen density, meaning that each pixel is
+physically larger and, thus, the entire screen is larger than the baseline (normal size) screen.</p>
-<p>Although the platform lets your application provide customized resources for
-the various size and density configurations, you do not need to do write
-custom code or provide custom resources for every combination of screen size and density.
-The platform provides robust compatibility features, described
-in the sections below, that can handle most of the work of rendering your
-application on any device screen, provided that you've implemented your
-application UI properly. For more information about how to implement a UI that
-renders properly across device screens and platform versions, see
-<a href="#screen-independence">Best Practices for Screen Independence</a>.</p>
-
-<p>To help you test your applications, the Android SDK includes emulator skins
-that replicate the sizes and densities of actual device screens on which your
-application is likely to run. You can also modify the default size and density
-of the emulator skins to replicate the characteristics of any specific
-screen.</p>
-
-<p class="table-caption" id="screens-table"><strong>Table 1.</strong> Screen
-sizes and densities of emulator skins included in the Android SDK and other
-representative resolutions.</p>
-
- <table>
- <tbody>
- <tr>
- <td style="border:none"></td>
- <td style="background-color:#f3f3f3">
- <nobr>Low density (120), <em>ldpi</em></nobr>
- </td>
- <td style="background-color:#f3f3f3">
- <nobr>Medium density (160), <em>mdpi</em></nobr>
- </td>
- <td style="background-color:#f3f3f3">
- <nobr>High density (240), <em>hdpi</em><nobr>
- </td>
- <td style="background-color:#f3f3f3">
- <nobr>Extra high density (320), <em>xhdpi</em><nobr>
- </td>
- </tr>
- <tr>
- <td style="background-color:#f3f3f3">
- <em>Small</em> screen
- </td>
- <td style="font-size:.9em;"><strong>QVGA (240x320)</strong></td>
- </td>
- <td></td>
- <td style="font-size:.9em;">480x640</td>
- <td></td>
- </tr>
- <tr>
- <td style="background-color:#f3f3f3">
- <em>Normal</em> screen
- </td>
- <td style="font-size:.9em;"><strong>WQVGA400 (240x400)</strong>
- <br><strong>WQVGA432 (240x432)</strong></td>
- <td style="font-size:.9em;"><strong>HVGA (320x480)</strong></td>
- <td style="font-size:.9em;"><strong>WVGA800 (480x800)</strong>
- <br><strong>WVGA854 (480x854)</strong>
- <br>600x1024</td>
- <td style="font-size:.9em;">640x960</td>
- </tr>
- <tr>
- <td style="background-color:#f3f3f3">
- <em>Large</em> screen
- </td>
- <td style="font-size:.9em;"><strong>WVGA800** (480x800)</strong>
- <br><strong>WVGA854** (480x854)</strong></td>
- <td style="font-size:.9em;"><strong>WVGA800* (480x800)</strong>
- <br><strong>WVGA854* (480x854)</strong>
- <br>600x1024</td>
- <td></td>
- <td></td>
- </tr>
- <tr>
- <td style="background-color:#f3f3f3">
- <em>Extra Large</em> screen
- </td>
- <td style="font-size:.9em;">600x1024</td>
- <td style="font-size:.9em;">768x1024<br><strong>WXGA (768x1280)</strong>
- <br>800x1280</td>
- <td style="font-size:.9em;">1152x1536<br>1152x1920
- <br>1200x1920</td>
- <td style="font-size:.9em;">1536x2048<br>1536x2560
- <br>1600x2560</td>
- </tr>
- <tr>
- <td colspan="4" style="border:none;font-size:90%;">* To emulate this
- configuration, specify a custom density of 160 when
- creating an AVD that uses a WVGA800 or WVGA854 skin.
- </td>
- </tr>
- <tr>
- <td colspan="4" style="border:none;font-size:90%;">** To emulate this
- configuration, specify a custom density of 120 when
- creating an AVD that uses a WVGA800 or WVGA854 skin.
- </td>
- </tr>
-</table>
-
-<p>For an overview of the relative numbers of high (hdpi), medium (mdpi), and
-low (ldpi) density screens in Android-powered devices available now, see the <a
-href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a> dashboard.</p>
-
-
-<h3 id="support">How Android supports multiple screens</h3>
-
-<div class="sidebox-wrapper">
-<div class="sidebox">
-<h2>Using the alternative resources framework</h2>
-
-<p>The platform's support for loading screen size- and density-specific
-resources at run time is based on the alternative resources framework.
-
-<p> If you want to use size- or density-specific layouts or drawables in your
-application and you are not familiar with resource qualifiers or how the
-platform uses them, please read
-<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
-Providing Alternative Resources</a>.
-</div>
-</div>
-
-<p>The foundation of Android's support for multiple screens is a set of built-in
-compatibility features that together manage the rendering of application
-resources in an appropriate way for the current device screen. The platform
-handles most of the work of rendering your application, but also gives you two
-key ways to control how your application is displayed, if you need or want
-to use them:</p>
-
-<ul>
- <li>The platform supports a set of resource qualifiers that let you provide
-size- and density-specific resources, if needed. The qualifiers for
-size-specific resources are <code>small</code>, <code>normal</code>, <code>large</code>, and
-<code>xlarge</code>. Those for density-specific resources are <code>ldpi</code>
-(low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and <code>xhdpi</code> (extra high).
-The qualifiers correspond to the generalized densities described in
-<a href="#range">Range of screens supported</a>, above.</li>
- <li>The platform also provides a
-<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html">
-<code><supports-screens></code></a>
-manifest element, whose attributes
-<code>android:smallScreens</code>, <code>android:normalScreens</code>,
-<code>android:largeScreens</code>, and <code>android:xlargeScreens</code> let you specify what
-generalized screen sizes
-your application supports. Another attribute, <code>android:anyDensity</code>,
-lets you indicate whether or not your application includes built-in support for
-multiple densities.</li>
-</ul>
-
-<p>At run time, the platform provides three types of support to your
-application, to ensure the best possible display on the current device
-screen:</p>
-
-<ol>
-<li><em>Pre-scaling of resources (such as image assets)</em>
-
- <p>Based on the density of the current screen, the platform automatically
-loads any size- or density-specific resources from your application and displays
-them without scaling. If no matching resources are available, the platform loads
-the default resources and scales them up or down as needed to match the current
-screen's generalized density. The platform assumes that default resources are
-designed for proper display at the baseline screen density of "medium" (160),
-unless they are loaded from a density-specific resource directory.</p>
-
- <p>For example, if the current screen's density is "high", the platform loads
-resources that are tagged with the qualifier <code>hdpi</code> and uses them
-without scaling. If no such resources are available, the platform uses the
-default resources instead, scaling them from the baseline density ("medium") to
-"high". </p>
-
- <p>For more information about how to create size- and density-specific
-resources, see <a href="#qualifiers">Resource qualifiers</a>.</p></li>
-
-<li><em>Auto-scaling of pixel dimensions and coordinates</em>
-
- <p>If the application states that it does not support different screen
-densities, the platform auto-scales any absolute pixel coordinates, pixel
-dimension values, and pixel math used in the application (such as might be used
-for specifying the width or padding for a view). It does this to ensure that
-pixel-defined screen elements are displayed at approximately the same physical
-size as they would be at the baseline density of "medium" (160). The platform
-handles this scaling transparently to the application and also reports scaled
-overall pixel dimensions to the application, rather than physical pixel
-dimensions. </p>
-
- <p>For instance, suppose a given device is using a WVGA high-denisty screen,
-which is 480x800 and about the same size as a traditional HVGA screen, but it's
-running an app that states that it does not support multiple densities. In this
-case, the system will "lie" to the application when it queries for screen
-dimensions, and report 320x533. Then, when the app does drawing operations, such
-as invalidating the rectangle from (10,10) to (100, 100), the system will
-likewise automatically transform the coordinates by scaling them the appropriate
-amount, and actually invalidate the region (15,15) to (150, 150). The same
-thing happens in the other direction, if the application is running on a
-lower-density screen, coordinates are scaled down.<p>
-
- <p>For more information, see the <code>android:anyDensity</code> attribute in
-<a href="#attrs">Manifest attributes for screens support</a>.</p></li>
-
-<div class="sidebox-wrapper" xstyle="margin-bottom:2em;margin-top:.5em;width:90%;">
- <img id="rule" src="{@docRoot}assets/images/grad-rule-qv.png">
- <div id="qv-sub-rule">
- <img src="{@docRoot}assets/images/icon_market.jpg" style="float:left;margin:0;padding:0;">
- <p style="color:#669999;">Publishing to Small Screen Devices</p>
- <p>To ensure the best experience for users on small-screen devices, Android
-Market only shows applications that explicitly declare support for small
-screens. If you developed an application on Android 1.5 or earlier and published
-it on Android Market, you need to <a href="#testing">test your application</a>
-on small screens and then upload an updated version that explicitly
-<a href="#attrs">indicates support for small screens</a>. </p>
- </div>
-</div>
-
-<li><em>Compatibility-mode display on larger screen-sizes</em>
-
- <p>If the current screen's size is larger than your application supports, as
-specified in the <code>supports-screens</code> element, the platform displays
-the application at the baseline size ("normal") and density ("medium). For
-screens larger than baseline, the platform displays the application in a
-baseline-sized portion of the overall screen, against a black background. </p>
-
- <p>For instance, suppose a given device is using a WVGA medium density screen,
-classified as a "large" screen, but the application states that it does not
-support large screens; in this case, the system will again "lie" to the
-application when it queries for screen dimensions, and report 320x480. Instead
-of scaling the application, however, the application's 320x480 interface will be
-placed as a "postage stamp" in the larger 480x800 screen.</p>
-
- <p>For more information, see the <code>android:anyDensity</code> attribute in
-<a href="#attrs">Manifest elements for screens support</a> and the
-<a href="#compatibility-examples">Screen-Compatibility Examples</a>
-section.</p></li>
-</ol>
-
-<p>In general, these compatibility features ensure that all applications,
-including those written against Android 1.5 and earlier platform versions, can
-display properly on most devices, especially when the device's screen is at the
-baseline "normal" size or larger. </p>
-
-<p>However, note that applications written for the baseline screen may need
-minor adjustments before they display properly on smaller screens such as QVGA.
-With the reduced screen area of small screens, there may be tradeoffs in design,
-content, and function that you, as the application developer, need to consider.
-For more information about how to prepare an existing application for display on
-small screens, see <a href="#strategies">Strategies for Legacy
-Applications</a>.</p>
-
-<p>The sections below provide more information how to take advantage of the
-platform's multiple-screens support. </p>
<h3 id="density-independence">Density independence</h3>
-<p>The goal of density independence is to preserve the physical size, from the
-user's point of view, of user interface elements declared in an application,
-when the application is displayed on screens with different densities. Density
-independence applies to both layouts and drawables such as icons. Maintaining
-density-independence is important because, other things being equal, a UI
-element (such as a button) whose height and width are defined in terms of screen
-pixels will appear physically larger on the lower density screen and smaller on
-the higher density screen. Such density-related size changes can cause problems
-in application layout, usability, and consistency with other applications
-installed on the device.</p>
+<p>Your application achieves "density independence" when it preserves the physical size (from
+the user's point of view) of user interface elements when displayed on screens with different
+densities.</p>
-<p>The platform provides density independence to applications by default. It
-does this in three ways: </p>
+<p>Maintaining density independence is important because, without it, a UI element (such as a
+button) appears physically larger on a low density screen and smaller on a high density screen. Such
+density-related size changes can cause problems in your application layout and usability. Figures 2
+and 3 show the difference between an application when it does not provide density independence and
+when it does, respectively.</p>
+
+<img src="{@docRoot}images/screens_support/density-test-bad.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> Example application without support for
+different densities, as shown on low, medium, and high density screens.</p>
+
+<img src="{@docRoot}images/screens_support/density-test-good.png" alt="" />
+<p class="img-caption"><strong>Figure 3.</strong> Example application with good support for
+different densities (it's density independent), as shown on low, medium, and high
+density screens.</p>
+
+<p>The Android system helps your application achieve density independence in two ways: </p>
<ul>
-<li>Through pre-scaling of drawable resources (scaled at resource loading
-time)</li>
-<li>Through auto-scaling of density-independent pixel (dp) values used in
-layouts</li>
-<li>Through auto-scaling of absolute pixel values used in the application (only
-needed if the application has set <code>android:anyDensity="false"</code> in its
-manifest)</li>
+<li>The system scales dp units as appropriate for the current screen density</li>
+<li>The system scales drawable resources to the appropriate size, based on the current screen
+density, if necessary</li>
</ul>
-<p>The example screens below illustrate the density independence provided by the
-platform. Note that both the layouts and launcher icons are displayed at the
-same physical sizes, although screen sizes, aspect ratios, and densities are
-different.</p>
-
-
-<div id=vi09 style=TEXT-ALIGN:left>
-<img src="{@docRoot}images/screens_support/dip.png" style="padding-bottom:0;margin-bottom:0;" />
-<p class="caption" style="margin:0 0 1.5em 1em;padding:0 0 0
-1em;"><strong>Figure 2.</strong> Examples of density independence on WVGA high
-density (left), HVGA medium density (center), and QVGA low density (right). </p>
-</div>
-
-<p>In most cases, you can take advantage of density independence in your
-application simply by making sure that your layouts specify all dimension values
-in density-independent pixels (<code>dp</code> or <code>dp</code>) or
-scale-independent pixels (<code>sip</code> or <code>sp</code>, for text only).
-If you are using absolute pixel values in the application and manifest includes
-<a href="#attrs"><code>android:anyDensity="true"</code></a>, you will also need
-to scale the pixel values. See <a href="#dips-pels">Converting dp units to
-pixel units</a> for more information. </p>
-
-
-<h3 id="attrs">Manifest attributes for screens support</h3>
-
-<p> Android 1.6 introduced a new manifest element,
-<a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><code><supports-screens></code></a>,
-whose attributes you can use to control the
-display of your application on different classes of device screens, as listed
-in table 2. The <code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code> and
-<code>xlargeScreens</code> attributes correspond to the generalized screen sizes
-described in <a href="#range">Range of screens supported</a>, earlier in this
-document. Notice that the default values for each attribute vary, depending
-on your minimum and targeted platform, as indicated in the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-android:minSdkVersion}</a> and <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-android:targetSdkVersion}</a> attributes of your <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a>
-manifest element.</p>
-
-<p class="table-caption" id="table2"><strong>Table 2.</strong> Summary of attributes for the <a
-href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code
-<supports-screens>}</a> manifest element, including default values based on platform
-version.</p>
- <table id="vrr8">
- <tr>
- <th>
- Attribute
- </th>
- <th >
- Description
- </th>
- <th>
- Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
-<code>targetSdkVersion</code> is 4 or lower
- </th>
- <th>
- Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
-<code>targetSdkVersion</code> is 5 or higher
- </th>
- </tr>
- <tr>
- <td>
- <code>android:smallScreens</code>
- </td>
- <td>
- Whether or not the application UI is designed for use on
-<em>small</em> screens — "<code>true</code>" if it is, and
-"<code>false</code>" if not. </p>
- </td>
-<td>"<code>false</code>"</td>
-<td>"<code>true</code>"</td>
- </tr>
- <tr>
- <td>
- <code>android:normalScreens</code>
- </td>
- <td>
- Whether or not the application UI is designed for use on
-<em>normal</em> screens — "<code>true</code>" if it is, and
-"<code>false</code>" if not. The default value is always "<code>true</code>".
- </td>
-<td>"<code>true</code>"</td>
-<td>"<code>true</code>"</td>
- </tr>
- <tr>
- <td>
- <code>android:largeScreens</code>
- </td>
- <td>
- Whether or not the application UI is designed for use on
-<em>large</em> screens — "<code>true</code>" if it is, and
-"<code>false</code>" if not.
- </td>
-<td>"<code>false</code>"</td>
-<td>"<code>true</code>"</td>
- </tr>
- <tr>
- <td>
- <code>android:anyDensity</code>
- </td>
- <td>
- <p>Whether or not the application is designed to manage its UI properly
-in different density environments — "<code>true</code>" if so, and
-"<code>false</code>" if not. </p>
- <ul>
- <li>If set to "<code>true</code>", the platform disables its
-density-compatibility features for all screen densities — specifically,
-the auto-scaling of absolute pixel units (<code>px</code>) and math — and
-relies on the application to use density-independent pixel units
-(<code>dp</code>) and/or math to manage the adaptation of pixel values according
-to density of the current screen. That is, as long as your application uses
-density-independent units (dp) for screen layout sizes, then it will perform
-properly on different densities when this attribute is set to
-"<code>true</code>".</li>
-
- <li>If set to "<code>false</code>", the platform enables its
-density-compatibility features for all screen densities. In this case, the
-platform provides a scaled, virtual screen pixel map to the application, against
-which it can layout and draw its UI as though against a medium-density screen
-(160). The platform then transparently auto-scales the application's pixel units
-and math as needed to match the actual device screen density. </li>
- </ul>
-<p>Note that the setting of this attribute affects density-compatibility only.
-It does not affect size-compatibility features such as display on a virtual
-baseline screen.</p>
- </td>
-<td>"<code>false</code>"</td>
-<td>"<code>true</code>"</td>
- </tr>
- <tr>
- <td colspan="4"><strong>Note:</strong> Android 2.3 (API Level 9) introduced a new
-attribute for the <code><supports-screens></code> element: <code>xlargeScreens</code>, shown
-below. It works the same as the other screen attributes above, but, if neither your
-<code>minSdkVersion</code> or <code>targetSdkVersion</code> are set to "9", the default value is
-"false" when your application is installed on a device running Android 2.3.</td>
- </tr>
- <tr>
- <th>
- Attribute
- </th>
- <th >
- Description
- </th>
- <th>
- Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
-<code>targetSdkVersion</code> is 8 or lower
- </th>
- <th>
- Default value, when<br><nobr><code>minSdkVersion</code> or</nobr>
-<code>targetSdkVersion</code> is 9 or higher
- </th>
- </tr>
- <tr>
- <td>
- <code>android:xlargeScreens</code>
- </td>
- <td>
- Whether or not the application UI is designed for use on
-<em>xlarge</em> screens — "<code>true</code>" if it is, and
-"<code>false</code>" if not.
- </td>
-<td>"<code>false</code>"</td>
-<td>"<code>true</code>"</td>
- </tr>
- </table>
-
-<p>In general, when you declare a screen-size attribute
-(<code>smallScreens</code>, <code>normalScreens</code>, <code>largeScreens</code>, or
-<code>xlargeScreens</code>) as "<code>true</code>", you are signaling to the
-platform that your application is designed to render properly on that screen
-size. As a result, the platform does not apply any size-compatibility features
-(such as a virtual HVGA display area). If you declare a screen-size attribute as
-"<code>false</code>", you are signaling that your application is <em>not</em>
-designed for that screen size. In this case, the platform <em>does</em> apply
-size-compatibility features, rendering the application in an HVGA baseline
-display area. If the current screen is larger than <em>normal</em> size, the
-platform renders the application in a virtual HVGA screen on the larger screen.
-See <a href="#compatibility-examples">Screen-Compatibility Examples</a> for an
-illustration of what an application looks like when displayed in a virtual HVGA
-screen.</p>
-
-<p>In other words, setting a <code><supports-screens></code> attribute to
-"<code>false</code>" tells the platform to enable it's compatibility features
-when displaying the application on a screen of that size <em>or any larger
-size</em>, if also disallowed. Otherwise, the platform gives the application a
-normal display area that can use the full device screen area, if
+<p>In figure 2, the text view and bitmap drawable have dimensions specified in pixels ({@code px}
+units), so the elements are physically larger on a low density screen and smaller on a high density
+screen. This is because although the actual screen sizes may be the same, the high density screen
+has more pixels per inch (the same amount of pixels fit in a smaller area). In figure 3, the layout
+dimensions are specified in density-independent pixels ({@code dp} units). Because the baseline for
+density-independent pixels is a medium-density screen, the device with a medium-density screen looks
+the same as it does in figure 2. For the low-density and high-density screens, however, the system
+scales the density-independent pixel values down and up, respectively, to fit the screen as
appropriate.</p>
-<p>Android Market also makes use of the <code><supports-screens></code>
-attributes. It uses them to filter the application from devices whose screens
-are not supported by the application. Specifically, Android Market considers an
-application compatible with a device if the application supports a screen that
-is the same or smaller than the current device screen. Android Market filters
-the application if it disallows the device's screen size and does not support a
-smaller size. In general, Android does not provide downward size-compatibility
-features for applications.</p>
+<p>In most cases, you can ensure density independence in your application simply by specifying all
+layout dimension values in density-independent pixels (<code>dp</code> units) or with {@code
+"wrap_content"}, as appropriate. The system then scales bitmap drawables as appropriate in order to
+display at the appropriate size, based on the appropriate scaling factor for the current screen's
+density.</p>
-<p>Here are some examples:</p>
+<p>However, bitmap scaling can result in blurry or pixelated bitmaps, which you might notice in the
+above screenshots. To avoid these artifacts, you should provide alternative bitmap resources for
+different densities. For example, you should provide higher-resolution bitmaps for high-density
+screens and the system will use those instead of resizing the bitmap designed for medium-density
+screens. The following section describes more about how to supply alternative resources for
+different screen configurations.</p>
+
+
+
+<h2 id="support">How to Support Multiple Screens</h2>
+
+<p>The foundation of Android's support for multiple screens is its ability to manage the rendering
+of an application's layout and bitmap drawables in an appropriate way for the current screen
+configuration. The system handles most of the work to render your application properly on each
+screen configuration by scaling layouts to fit the screen size/density and scaling bitmap drawables
+for the screen density, as appropriate. To more gracefully handle different screen configurations,
+however, you should also:</p>
<ul>
- <li>Assume that you declare <code>smallScreens="false" normalScreens="true"
-largeScreens="false" xlargeScreens="false"</code> in your application's manifest. <p>Although the
-application is not designed for display on large or extra large screens, the platform can still
-run it successfully in <a href="#compatibility-examples">screen-compatibility
-mode</a>. Android Market shows the application to devices with
-<em>normal</em>, <em>large</em>, and <em>xlarge</em> size screens, but does filter it from
-<em>small</em> size screens, because the application provides no screen support at
-<em>small</em> size. Android's <a href="#compatibility-examples">screen-compatibility
-mode</a> mode does not provide support for screens that are smaller than those the
-application supports—it only provides support for screens that are larger. Thus,
-although the application declares "false" for <em>large</em> and <em>xlarge</em> screens,
-the application still functions, but runs in compatibility mode.</p></li>
-
- <li>Assume that you declare <code>smallScreens="false" normalScreens="false"
-largeScreens="true" xlargeScreens="true"</code> in your application's manifest. <p>Android Market
-filters the application from users of devices with <em>small</em> and
-<em>normal</em> size screens. In effect, this prevents such users from
-installing the application.</p></li>
+ <li><strong>Provide different layouts for different screen sizes</strong>
+ <p>By default, Android resizes your application layout to fit the current device screen. In most
+cases, this works fine. In other cases, your UI might not look as good and might need adjustments
+for different screen sizes. For example, on a larger screen, you might want to adjust the position
+and size of some elements to take advantage of the additional screen space, or on a smaller screen,
+you might need to adjust sizes so that everything can fit on the screen.</p>
+ <p>The configuration qualifiers you can use to provide size-specific resources are
+<code>small</code>, <code>normal</code>, <code>large</code>, and <code>xlarge</code>. For
+example, layouts for an extra large screen should go in {@code layout-xlarge/}.</p>
+ </li>
+
+ <li><strong>Provide different bitmap drawables for different screen densities</strong>
+ <p>By default, Android scales your bitmap drawables ({@code .png}, {@code .jpg}, and {@code
+.gif} files) and Nine-Patch drawables ({@code .9.png} files) so that they render at the appropriate
+physical size on each device. For example, if your application provides bitmap drawables only for
+the baseline, medium screen density (mdpi), then the system scales them up when on a high-density
+screen, and scales them down when on a low-density screen. This scaling can cause artifacts in the
+bitmaps. To ensure your bitmaps look their best, you should include alternative versions at
+different resolutions for different screen densities.</p>
+ <p>The configuration qualifiers you can use for density-specific resources are
+<code>ldpi</code> (low), <code>mdpi</code> (medium), <code>hdpi</code> (high), and
+<code>xhdpi</code> (extra high). For example, bitmaps for high-density screens should go in
+{@code drawable-hdpi/}.</p>
+ </li>
</ul>
-<p>If you declare the <code>android:anyDensity</code> attribute as
-"<code>true</code>", you are signaling to the platform that your application is
-designed to display properly on any screen density. In this case, the
-application must ensure that it declares its UI dimensions using
-density-independent pixels (<code>dp</code>) and scales any absolute pixel
-values (<code>px</code>) or math by the scaling factor available from {@link
-android.util.DisplayMetrics#density android.util.DisplayMetrics.density}. See <a
-href="#dips-pels">Converting dp units to pixel units</a> for an example.</p>
+<p>The size and density configuration qualifiers correspond to the generalized sizes and densities
+described in <a href="#range">Range of screens supported</a>, above.</p>
-<p>Note that the setting of the <code>android:anyDensity</code> attribute does
-not affect the platform's pre-scaling of drawable resources, such as bitmaps and
-nine-patch images, which always takes place by default. </p>
+<p class="note"><strong>Note:</strong> If you're not familiar with configuration qualifiers and how
+the system uses them to apply alternative resources, read <a
+href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Providing
+Alternative Resources</a> for more information.</p>
-<p>The following example shows a manifest that declares support for small, normal, large, and
- xlarge screens in any density.</p>
+<p>At runtime, the system ensures the best possible display on the current screen with
+the following procedure for any given resource:</p>
-<pre>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android">
- <supports-screens
- android:smallScreens="true"
- android:normalScreens="true"
- android:largeScreens="true"
- android:xlargeScreens="true"
- android:anyDensity="true" />
- ...
-</manifest>
-</pre>
-<!-- android:resizeable="true" -->
-<h4 id="defaults">
- Default values for attributes
-</h4>
+<ol>
+<li>The system uses the appropriate alternative resource
+ <p>Based on the size and density of the current screen, the system uses any size- and
+density-specific resource provided in your application. For example, if the device has a
+high-density screen and the application requests a drawable resource, the system looks for a
+drawable resource directory that best matches the device configuration. Depending on the other
+alternative resources available, a resource directory with the {@code hdpi} qualifier (such as
+{@code drawable-hdpi/}) might be the best match, so the system uses the drawable resource from this
+directory.</p>
+</li>
-<p>The default values for the <code><supports-screens></code> attributes
-differ, depending on the the value of the
-<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><code>android:minSdkVersion</code></a>
- attribute in the application's manifest, as well as on
-the value of <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-android:targetSdkVersion}</a>, if declared.</p>
+<li>If no matching resource is available, the system uses the default resource and scales it up
+or down as needed to match the current screen size and density
+ <p>The "default" resources are those that are not tagged with a configuration qualifier. For
+example, the resources in {@code drawable/} are the default drawable resources. The system
+assumes that default resources are designed for the baseline screen size and density, which is a
+normal screen size and a medium density. As such, the system scales default density
+resources up for high-density screens and down for low-density screens, as appropriate.</p>
+ <p>However, when the system is looking for a density-specific resource and does not find it in
+the density-specific directory, it won't always use the default resources. The system may
+instead use one of the other density-specific resources in order to provide better results
+when scaling. For example, when looking for a low-density resource and it is not available, the
+system prefers to scale-down the high-density version of the resource, because the
+system can easily scale a high-density resource down to low-density by a factor of 0.5, with
+fewer artifacts, compared to scaling a medium-density resource by a factor of 0.75.</p>
+</li>
+</ol>
-<p>Above, <a href="#table2">table 2</a> indicates the default values for each attribute, based on
-the values you provide for the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-android:minSdkVersion}</a> and <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code
-android:targetSdkVersion}</a>, in the <a
-href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a>
-element.</p>
-
-<p class="note"><strong>Note:</strong> If your application uses APIs introduced in Android 1.6 or
-higher, but does not support specific screen densities and/or screen sizes, you need to explicitly
-set the appropriate attributes to "<code>false</code>" (because most are "true", by default).</p>
+ <p>For more information about how Android selects alternative resources by matching configuration
+qualifiers to the device configuration, read
+<a href="{@docRoot}guide/topics/resources/providing-resources.html#BestMatch">How Android
+Finds the Best-matching Resource</a>.</p>
-<h3 id="qualifiers">Resource directory qualifiers for screen size and density</h3>
-<p>Android supports resource directory qualifiers for controlling the selection
-of resources based on the characteristics of the screen on which your application
-is running. You can use these qualifiers to provide size- and density-specific
-resources in your application. For more information about the generalized sizes
-and densities that correspond to the qualifiers, see <a href="#range">Range
-of Screens Supported</a>, earlier in this document.</p>
+
+<h3 id="qualifiers">Using configuration qualifiers</h3>
+
+<p>Android supports several configuration qualifiers that allow you to control how the system
+selects your alternative resources based on the characteristics of the current device screen. A
+configuration qualifier is a string that you can append to a resource directory in your Android
+project and specifies the configuration for which the resources inside are designed.</p>
+
+<p>To use a configuration qualifier:</p>
+<ol>
+ <li>Create a new directory in your project's {@code res/} directory and name it using the
+format: <nobr>{@code <resources_name>-<qualifier>}</nobr>
+ <ul>
+ <li>{@code <resources_name>} is the standard resource name (such as {@code drawable} or
+{@code layout}).</li>
+ <li>{@code <qualifier>} is a configuration qualifier from table 1, below, specifying the
+screen configuration for which these resources are to be used (such as {@code hdpi} or {@code
+xlarge}).</li>
+ </ul>
+ <p>You can use more than one {@code <qualifier>} at a time—simply separate each
+qualifier with a dash.</p>
+ </li>
+ <li>Save the appropriate configuration-specific resources in this new directory. The resource
+files must be named exactly the same as the default resource files.</li>
+</ol>
+
+<p>For example, {@code xlarge} is a configuration qualifier for extra large screens. When you append
+this string to a resource directory name (such as {@code layout-xlarge}), it indicates to the
+system that these resources are to be used on devices that have an extra large screen.</p>
+
+<p class="table-caption"><strong>Table 1.</strong> Configuration qualifiers that allow you to
+provide special resources for different screen configurations.</p>
<table>
<tr>
@@ -784,691 +370,627 @@
<tr>
<td rowspan="4">Size</td>
<td><code>small</code></td>
- <td>Resources designed for <em>small</em> size screens.</td>
+ <td>Resources for <em>small</em> size screens.</td>
</tr>
<tr>
<td><code>normal</code></td>
- <td>Resources designed for <em>normal</em> size screens.</td>
+ <td>Resources for <em>normal</em> size screens. (This is the baseline size.)</td>
</tr>
<tr>
<td><code>large</code></td>
-<td>Resources designed for <em>large</em> size screens.</td>
+<td>Resources for <em>large</em> size screens.</td>
</tr>
<tr>
<td><code>xlarge</code></td>
-<td>Resources designed for <em>extra large</em> size screens.</td>
+<td>Resources for <em>extra large</em> size screens.</td>
</tr>
<tr>
<td rowspan="5">Density</td>
<td><code>ldpi</code></td>
-<td>Resources designed for low-density (<em>ldpi</em>) screens.</td>
+<td>Resources for low-density (<em>ldpi</em>) screens (~120dpi).</td>
</tr>
<tr>
<td><code>mdpi</code></td>
-<td>Resources designed for medium-density (<em>mdpi</em>) screens.</td>
+<td>Resources for medium-density (<em>mdpi</em>) screens (~160dpi). (This is the baseline
+density.)</td>
</tr>
<tr>
<td><code>hdpi</code></td>
-<td>Resources designed for high-density (<em>hdpi</em>) screens.</td>
+<td>Resources for high-density (<em>hdpi</em>) screens (~240dpi).</td>
</tr>
<tr>
<td><code>xhdpi</code></td>
-<td>Resources designed for extra high-density (<em>xhdpi</em>) screens.</td>
+<td>Resources for extra high-density (<em>xhdpi</em>) screens (~320dpi).</td>
</tr>
<tr>
<td><code>nodpi</code></td>
-<td>Density-independent resources. The platform does not auto-scale resources
-tagged with this qualifier, regardless of the current screen's density.</td>
+<td>Resources for all densities. These are density-independent resources. The system does not
+scale resources tagged with this qualifier, regardless of the current screen's density.</td>
+</tr>
+
+<tr>
+<td rowspan="2">Orientation</td>
+<td><code>land</code></td>
+<td>Resources for screens in the landscape orientation (wide aspect ratio).</td>
+</tr>
+<tr>
+<td><code>port</code></td>
+<td>Resources for screens in the portrait orientation (tall aspect ratio).</td>
</tr>
<tr>
<td rowspan="2">Aspect ratio</td>
<td><code>long</code></td>
-<td>Resources for screens of any size or density that have a significantly
-taller (in portrait mode) and wider (in landscape mode) aspect ratio than the
-baseline screen configuration.</td>
+<td>Resources for screens that have a significantly taller or wider aspect ratio (when in portrait
+or landscape orientation, respectively) than the baseline screen configuration.</td>
</tr>
<tr>
<td><code>notlong</code></td>
-<td>Resources for use only on screens that have an aspect ratio that is similar
-to the baseline screen configuration.</td>
-</tr>
-<tr>
-<td>Platform version</td>
-<td><nobr><code>v<api-level></code></nobr></td>
-<td>Resources that are for use only on a specific API Level or higher. For
-example, if your application is designed to run on both Android 1.5 (API Level
-3) and Android 1.6 (API Level 4 and higher), you can use the <code>-v4</code>
-qualifier to tag any resources that should be excluded when your application is
-running on Android 1.5 (API Level 3). </td>
+<td>Resources for use screens that have an aspect ratio that is similar to the baseline screen
+configuration.</td>
</tr>
</table>
-<p>
-Note that the density and the screen size are independent parameters and are
-interpreted by the system individually. For example, WVGA high density is
-considered a normal screen because its physical size is about the same as one of
-T-Mobile G1. On the other hand, a WVGA medium density screen is considered a
-<i>large</i> screen — it offers the same resolution but at lower pixel
-density, meaning that it is both physically larger than the baseline screen and
-can display significantly more information than a normal screen size.
-</p>
+<p>For more information about how these qualifiers roughly correspond to real screen
+sizes and densities, see <a href="#range">Range of Screens Supported</a>, earlier in this
+document.</p>
-<p>Here is an example of the resource directory structure of an application that
-employs different layout schemes for different screen sizes and supports low and high density
-screens.</p>
+<p>For example, the following is a list of resource directories in an application that
+provides different layout designs for different screen sizes and different bitmap drawables
+for medium, high, and extra high density screens.</p>
-<pre>
-res/layout/my_layout.xml // layout for normal screen size
-res/layout-small/my_layout.xml // layout for small screen size
-res/layout-large/my_layout.xml // layout for large screen size
-res/layout-large-land/my_layout.xml // layout for large screen size in landscape mode
-res/layout-xlarge/my_layout.xml // layout for extra large screen size
+<pre class="classic">
+res/layout/my_layout.xml // layout for normal screen size ("default")
+res/layout-small/my_layout.xml // layout for small screen size
+res/layout-large/my_layout.xml // layout for large screen size
+res/layout-xlarge/my_layout.xml // layout for extra large screen size
+res/layout-xlarge-land/my_layout.xml // layout for extra large in landscape orientation
-res/drawable-lhdpi/my_icon.png // image for low density
-res/drawable-mdpi/dpi/my_icon.png // image for medium density
-res/drawable-hdpi/my_icon.png // image for high density
-
-res/drawable-nodpi/composite.xml // density independent resource
+res/drawable-mdpi/my_icon.png // bitmap for medium density
+res/drawable-hdpi/my_icon.png // bitmap for high density
+res/drawable-xhdpi/my_icon.png // bitmap for extra high density
</pre>
-<p>For more information about how to use resource qualifiers or how the platform
-selects them, please read
+<p>For more information about how to use alternative resources and a complete list of
+configuration qualifiers (not just for screen configurations), see
<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
Providing Alternative Resources</a>.</p>
+ <p class="note"><strong>Tip:</strong> If you have some drawable resources that the system
+should never scale (perhaps because you perform some adjustments to the image yourself at
+runtime), you should place them in a directory with the {@code nodpi} configuration qualifier.
+Resources with this qualifier are considered density-agnostic and the system will not scale
+them.</p>
-<h2 id="screen-independence">Best practices for Screen Independence</h2>
-<p>The objective of supporting multiple screens is to create an application that
-can run properly on any display and function properly on any of the generalized
-screen configurations supported by the platform.
-</p>
+<h3 id="DesigningResources">Designing alternative layouts and drawables</h3>
-<p>You can easily ensure that your application will display properly on
-different screens. Here is a quick checklist:</p>
+<p>The types of alternative resources you should create depends on your application's needs.
+Usually, you should use the size and orientation qualifiers to provide alternative layout resources
+and use the density qualifiers to provide alternative bitmap drawable resources.</p>
-<ol>
- <li>
- Use {@code wrap_content}, {@code fill_parent}, or the {@code dp} unit (instead of {@code px}),
-when specifying dimensions in an XML layout file
- </li>
- <li>
- Do not use {@code AbsoluteLayout}
- </li>
- <li>
- Do not use hard coded pixel values in your code
- </li>
- <li>
- Use density and/or resolution specific resources
- </li>
-</ol>
+<p>The following sections summarize how you might want to use the size and density qualifiers to
+provide alternative layouts and drawables, respectively.</p>
-<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit, instead of
-absolute pixels<br> </h3>
-<p>When defining the <code>layout_width</code> and <code>layout_height</code> of
-views in an XML layout file, using <code>wrap_content</code>,
-<code>fill_parent</code> or the <code>dp</code> will guarantee that the view is
-given an appropriate size on the current device screen. For instance, a view
-with a <code>layout_width="100dp"</code> will measure 100 pixels wide on an
-HVGA@160 density display and 150 pixels on a WVGA@240 density display, but the
-view will occupy approximately the same physical space. </p>
+<h4>Alternative layouts</h4>
-<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel,
-the scale factor depends on a user setting) or <code>dp</code> (if you don't
-want to allow the user to scale the text) to define font sizes.</p>
+<p>Generally, you'll know whether you need alternative layouts for different screen sizes once
+you test your application on different screen configurations. For example:</p>
-<h3 id="avoid-absolute">2. Avoid AbsoluteLayout </h3>
+<ul>
+ <li>When testing on a small screen, you might discover that your layout doesn't quite fit on the
+screen. For example, a row of buttons might not fit within the width of the screen on a small screen
+device. In this case you should provide an alternative layout for small screens that adjusts the
+size or position of the buttons.</li>
+ <li>When testing on an extra large screen, you might realize that your layout doesn't make
+efficient use of the big screen and is obviously stretched to fill it.
+In this case, you should provide an alternative layout for extra large screens that provides a
+redesigned UI that is optimized for bigger screens such as tablets.
+ <p>Although your application should work fine without an alternative layout on big screens, it's
+quite important to users that your application looks as though it's designed specifically for their
+devices. If the UI is obviously stretched, users are more likely to be unsatisfied with the
+application experience.</p></li>
+ <li>And, when testing in the landscape orientation compared to the portrait orientation, you
+might notice that UI elements placed at the bottom of the screen for the portrait orientation
+should instead be on the right side of the screen in landscape orientation.</li>
+</ul>
-<p>{@link android.widget.AbsoluteLayout AbsoluteLayout}
-is one of the layout containers offered by the Android UI toolkit. Unlike the
-other layouts however, <code>AbsoluteLayout</code> enforces the use of fixed
-positions which might easily lead to user interfaces that do not work well on
-different displays. Because of this, <code>AbsoluteLayout</code> was deprecated
-in Android 1.5 (API Level 3). </p>
+<p>To summarize, you should be sure that your application layout:</p>
+<ul>
+ <li>Fits on small screens (so users can actually use your application)</li>
+ <li>Is optimized for bigger screens to take advantage of the additional screen space</li>
+ <li>Is optimized for both landscape and portrait orientations</li>
+</ul>
-<p>You can achieve much the same layout by using a
-{@link android.widget.FrameLayout FrameLayout} instead, and setting
-<code>layout_margin</code> attributes of the children. This approach is more
-flexible and will yield better results on different screens.</p>
+<p>If your UI uses bitmaps that need to fit the size of a view even after the system scales
+the layout (such as the background image for a button), you should use <a
+href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">Nine-Patch</a> bitmap files. A
+Nine-Patch file is basically a PNG file in which you specific two-dimensional regions that are
+stretchable. When the system needs to scale the view in which the bitmap is used, the system
+stretches the Nine-Patch bitmap, but stretches only the specified regions. As such, you don't
+need to provide different drawables for different screen sizes, because the Nine-Patch bitmap can
+adjust to any size. You should, however, provide alternate versions of your Nine-Patch files for
+different screen densities.</p>
-<h3>3. Do not use hard-coded pixel values in your code</h3>
-<p>For performance reasons and to keep the code simpler, the Android framework
-API uses pixels as the standard unit for expressing dimension or coordinate
-values. That means that the dimensions of a View are always expressed in the
-code in pixels. For instance, if <code>myView.getWidth()</code> returns 10, the
-view is 10 pixels wide. In some cases, you may need to scale the pixel values
-that you use in your code. The sections below provide more information. </p>
+<h4>Alternative drawables</h4>
-<h4 id="dips-pels">Converting dp units to pixel units</h4>
-
-<p>In some cases, you will need to express dimensions in <code>dp</code> and
-then convert them to pixels. Imagine an application in which a scroll gesture is
-recognized after the user's finger has moved by at least 16 pixels. On a
-baseline screen, the user will have to move his finger by 16 pixels / 160
-dpi = 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a
-device with a high (240) density display, the user will move his finger by only
-16 pixels / 240 dpi = 1/15th of an inch (or 1.7 mm.) The distance is much
-shorter and the application thus appears more sensitive to the user. To fix this
-issue, the gesture threshold must be expressed in the code in <code>dp</code>
-and then converted to actual pixels.</p>
-
-<pre>// The gesture threshold expressed in dp
-private static final float GESTURE_THRESHOLD_DP = 16.0f;
-
-// Convert the dps to pixels
-final float scale = getContext().getResources().getDisplayMetrics().density;
-mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>
-
-// Use mGestureThreshold as a distance in pixels
-</pre>
-
-<p>The {@link android.util.DisplayMetrics#density android.util.DisplayMetrics.density}
-field specifies the the scale factor you must use to
-convert dps to pixels according to the current screen density. You can access
-the current screen's metrics through a <code>Context</code> or
-<code>Activity</code>. On a medium (160) density screen,
-<code>DisplayMetrics.density</code> equals "1.0", whereas on a high (240)
-density screen it equals "1.5". You can refer to the documentation of the
-{@link android.util.DisplayMetrics DisplayMetrics}
-class for details.</p>
-
-<h4>Use pre-scaled configuration values</h4>
-
-<p>The {@link android.view.ViewConfiguration ViewConfiguration} class can be
-used to access the most common distances, speeds, and times used in the Android
-framework. For instance, the distance in pixels used by the framework as the
-scroll threshold can be obtained as follows:</p>
-
-<pre>ViewConfiguration.get(aContext).getScaledTouchSlop()</pre>
-
-<p>Methods starting with the <code>getScaled</code> prefix are guaranteed to return a value in pixels that will display properly regardless of the current screen density.</p>
-
-<h3>4. Use density and/or size-specific resources</h3>
-
-<div style="float: right;background-color:#fff;margin: 0;padding: 20px 0 20px 20px;">
-<img src="{@docRoot}images/screens_support/scale-test.png" style="padding:0;margin:0;">
-<p class="caption" style="margin:0;padding:0;"><strong>Figure 3.</strong> Comparison of pre-scaled and auto-scaled bitmaps.</p>
+<div class="figure" style="width:223px;margin:0">
+<img src="{@docRoot}images/screens_support/screens-densities.png" alt="" />
+<p class="img-caption"><strong>Figure 4.</strong> Relative sizes for bitmap drawables
+that support each density.</p>
</div>
-<p>Even with the size- and density-compatibility features that the platform
-provides, you may still want to make adjustments to the UI of your application
-when it displayed on certain screen sizes or densities. You can do this by
-providing size- or density-specific resources — assets, layouts, strings,
-and so on. If you want, you can also take control over the scaling of images
-assets. The sections below provide more information.</p>
+<p>Almost every application should have alternative drawable resources for different screen
+densities, because almost every application has a launcher icon and that icon should look good on
+all screen densities. Likewise, if you include other bitmap drawables in your application (such
+as for menu icons or other graphics in your application), you should provide alternative versions or
+each one, for different densities.</p>
-<h4 id="resource-dirs">Custom resources and directories</h4>
+<p class="note"><strong>Note:</strong> You only need to provide density-specific drawables for
+bitmap files ({@code .png}, {@code .jpg}, or {@code .gif}) and Nine-Path files ({@code
+.9.png}). If you use XML files to define shapes, colors, or other <a
+href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resources</a>, you should
+put one copy in the default drawable directory ({@code drawable/}).</p>
+
+<p>To create alternative bitmap drawables for different densities, you should follow the
+<b>3:4:6:8 scaling ratio</b> between the four generalized densities. For example, if you have
+a bitmap drawable that's 48x48 pixels for medium-density screen (the size for a launcher icon),
+all the different sizes should be:</p>
+
+<ul>
+ <li>36x36 for low-density</li>
+ <li>48x48 for medium-density</li>
+ <li>72x72 for high-density</li>
+ <li>96x96 for extra high-density</li>
+</ul>
+
+<p>For more information about designing icons, see the <a
+href="{@docRoot}guide/practices/ui_guidelines/icon_design.html">Icon Design Guidelines</a>,
+which includes size information for various bitmap drawables, such as launcher icons, menu
+icons, status bar icons, tab icons, and more.</p>
+
+
+
+<h2 id="screen-independence">Best Practices</h2>
+
+<p>The objective of supporting multiple screens is to create an application that can function
+properly and look good on any of the generalized screen configurations supported by Android. The
+previous sections of this document provide information about how Android adapts your
+application to screen configurations and how you can customize the look of your application on
+different screen configurations. This section provides some additional tips and an overview of
+techniques that help ensure that your application scales properly for different screen
+configurations.</p>
+
+<p>Here is a quick checklist about how you can ensure that your application displays properly
+on different screens:</p>
+
+<ol>
+ <li>Use {@code wrap_content}, {@code fill_parent}, or {@code dp} units when specifying
+dimensions in an XML layout file</li>
+ <li>Do not use hard coded pixel values in your application code</li>
+ <li>Do not use {@code AbsoluteLayout} (it's deprecated)</li>
+ <li>Supply alternative bitmap drawables for different screen densities</li>
+</ol>
+
+<p>The following sections provide more details.</p>
+
+
+<h3 id="use-relative">1. Use wrap_content, fill_parent, or the dp unit for layout dimensions</h3>
+
+<p>When defining the <a
+href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_width"
+>{@code android:layout_width}</a> and <a
+href="{@docRoot}reference/android/view/ViewGroup.LayoutParams.html#attr_android:layout_height"
+>{@code android:layout_height}</a> for
+views in an XML layout file, using <code>"wrap_content"</code>,
+<code>"fill_parent"</code> or <code>dp</code> units guarantees that the view is
+given an appropriate size on the current device screen.</p>
+
+<p>For instance, a view with a <code>layout_width="100dp"</code> measures 100 pixels wide on
+medium-density screen and the system scales it up to 150 pixels wide on high-density screen, so
+that the view occupies approximately the same physical space on the screen.</p>
+
+<p>Similarly, you should prefer the <code>sp</code> (scale-independent pixel) to define text
+sizes. The <code>sp</code> scale factor depends on a user setting and the system scales the
+size the same as it does for {@code dp}.</p>
+
+
+<h3>2. Do not use hard-coded pixel values in your application code</h3>
+
+<p>For performance reasons and to keep the code simpler, the Android system uses pixels as the
+standard unit for expressing dimension or coordinate values. That means that the dimensions of a
+view are always expressed in the code using pixels, but always based on the current screen density.
+For instance, if <code>myView.getWidth()</code> returns 10, the view is 10 pixels wide on the
+current screen, but on a device with a higher density screen, the value returned might be 15. If you
+use pixel values in your application code to work with bitmaps that are not pre-scaled for the
+current screen density, you might need to scale the pixel values that you use in your code to match
+the un-scaled bitmap source.</p>
+
+<p>If your application manipulates bitmaps or deals with pixel values at runtime, see the section
+below about <a href="#DensityConsiderations">Additional Density Considerations</a>.</p>
+
+
+<h3 id="avoid-absolute">3. Do not use AbsoluteLayout </h3>
+
+<p>Unlike the other layouts widgets, {@link android.widget.AbsoluteLayout} enforces
+the use of fixed positions to lay out its child views, which can easily lead to user interfaces that
+do not work well on different displays. Because of this, {@link android.widget.AbsoluteLayout} was
+deprecated in Android 1.5 (API Level 3).</p>
+
+<p>You should instead use {@link android.widget.RelativeLayout}, which uses relative positioning
+to lay out its child views. For instance, you can specify that a button widget should appear "to
+the right of" a text widget.</p>
+
+
+<h3>4. Use size and density-specific resources</h3>
+
+<p>Although the system scales your layout and drawable resources based on the current screen
+configuration, you may want to make adjustments to the UI on different screen sizes and provide
+bitmap drawables that are optimized for different densities. This essentially reiterates the
+information from earlier in this document.</p>
<p>If you need to control exactly how your application will look on various
-displays, simply adjust your assets and layouts in configuration-specific
-resources directories. For example, consider an icon that you want to display on
+screen configurations, adjust your layouts and bitmap drawables in configuration-specific
+resource directories. For example, consider an icon that you want to display on
medium and high density screens. Simply create your icon at two different sizes
(for instance 100x100 for medium density and 150x150 for high density) and put
the two variations in the appropriate directories, using the proper
qualifiers:</p>
-<p style="margin-left:2em;"><code>res/drawable-mdpi/icon.png //
-for medium-density screens</code></p>
+<pre class="classic">
+res/drawable-mdpi/icon.png //for medium-density screens
+res/drawable-hdpi/icon.png //for high-density screens
+</pre>
-<p style="margin-left:2em;"><code>res/drawable-hdpi/icon.png //
-for high-density screens</code></p>
+<p class="note"><strong>Note:</strong> If a density qualifier is not defined in a directory name,
+the system assumes that the resources in that directory are designed for the baseline medium
+density and will scale for other densities as appropriate.</p>
-<p>If a density qualifier is not defined in a resource directory name, the
-platform assumes that the resources in that directory are designed for the
-baseline medium density. It is not recommended that you put density-specific
-resources such as images in the default directory.</p>
+<p>For more information about valid configuration qualifiers, see <a href="#qualifiers">Using
+configuration qualifiers</a>, earlier in this document.</p>
-<p>For more information about valid resource qualifiers, see
-<a href="#qualifiers">Resource directory qualifiers</a>, earlier in this
-document.</p>
-<h4 id="scaling">Pre-scaling and auto-scaling of bitmaps and nine-patches</h4>
-<p>When a bitmap or nine-patch image is loaded from the application's resources,
-the platform attempts to pre-scale it to match the display's density. For
-instance, if you placed a 100x100 icon in the <code>res/drawable/</code>
-directory and loaded that icon as a bitmap on a high-density screen, Android
-would automatically scale up the icon and produce a 150x150 bitmap.</p>
-<p>This pre-scaling mechanism works independently of the source. For instance,
-an application targeted for a high-density screen may have bitmaps only in the
-<code>res/drawable-hdpi/</code> directory. If one of the bitmaps is a 240x240
-icon and is loaded on a medium-density screen, the resulting bitmap will measure
-160x160.</p>
-<p>The platform pre-scales resources as needed, whether the application is
-running with density-compatibility features enabled or not (as specified by the
-value of <code>android:anyDensity</code>). However, when running with
-density-compatibility enabled, the platform continues to report the size of
-pre-scaled bitmaps and other resources as if they were loaded in a
-medium-density environment. For example, when density-compatibility is enabled,
-if you load a 76x76 image from the default resources for display on a
-high-density screen, the platform will pre-scale the image to 114x114
-internally. However, the API still reports the size of the image as 76x76. This
-discrepancy may cause unexpected behavior if your application somehow directly
-manipulates the scaled bitmap, but this was considered a reasonable trade-off to
-keep the performance of existing applications as good as possible.</p>
+<h2 id="DensityConsiderations">Additional Density Considerations</h2>
-<p>This does not apply for the case that an application creates an in-memory
-bitmap internally and draws something on it, for later display on the screen.
-The platform auto-scales such bitmaps on the fly, at draw time. Other side
-effects of such a case might be that fonts drawn in such a bitmap will be scaled
-at the bitmap level, when the off-screen bitmap is finally rendered to the
-display, resulting in scaling artifacts.</p>
+<p>This section describes more about how Android performs scaling for bitmap drawables on different
+screen densities and how you can further control how bitmaps are drawn on different densities. The
+information in this section shouldn't be important to most applications, unless you have encountered
+problems in your application when running on different screen densities or your application
+manipulates graphics.</p>
-<p>There are situations in which you may not want Android to automatically scale
-a resource. The easiest way to accomplish this is to put it in a "nodpi"
-resource directory:</p>
-
-<p style="margin-left:2em;"><code>res/drawable-nodpi/icon.png</code></p>
-
-<p>You can also take complete control of the scaling mechanism by using the
-{@link android.graphics.BitmapFactory.Options BitmapFactory.Options} class,
-which lets you define whether you want the bitmap to be pre-scaled and what the
-density of the bitmap should be. For instance, if you are loading a bitmap from
-a web server, you may want to force the bitmap's density to be high density.
-When pre-scaling is disabled, the resulting bitmap is in auto-scaling mode. The
-bitmap is associated with a density (that you may or may not have specified
-through the <code>BitmapFactory.Options</code>) which will be used to scale the
-bitmap on screen <em>at drawing time</em>.
-
-<p>Using auto-scaling instead of pre-scaling is more CPU expensive than
-pre-scaling but uses less memory. You can refer to the documentation of
-{@link android.graphics.BitmapFactory BitmapFactory},
-{@link android.graphics.Bitmap Bitmap}, and
-{@link android.graphics.Canvas Canvas} for more
-information on auto-scaling.</p>
-
-<p>Figure 3, at right, demonstrates the results of the pre-scale and auto-scale
-mechanisms when loading low (120), medium (160) and high (240) density bitmaps
-on a baseline screen. The differences are subtle, because all of the bitmaps are
-being scaled to match the current screen density, however the scaled bitmaps
-have slightly different appearances depending on whether they are pre-scaled or
-auto-scaled at draw time.</p>
-
-<h2 id="strategies">Strategies for Legacy Applications</h2>
-
-<p>If you have already developed and published an Android application based on
-Android 1.5 or earlier platform version, you need to consider how you will adapt
-your application so that it is deployable to:</p>
-
-<ul>
-<li>Existing devices, which may be running Android 1.5 (or lower) platform
-version, as well as to </li>
-<li>Newer devices that are running Android 1.6 (or higher) and offering various
-screen sizes and resolutions</li>
-</ul>
-
-<p class="note"><strong>Note:</strong> Even if your application targets Android 1.6 already, you
-should follow the same strategies below in order to support <em>xhdpi</em> and <em>xlarge</em>
-screens on Android 2.3 (API Level 9), while maintaining compatibility with older versions of
-the platform.</p>
-
-<p>To support the newer devices and the different screens they use, you might
-need to make some changes in your app, but at the same time your app may be very
-stable and so you want to minimize the changes. There are a variety of ways that
-you can extend your existing application to support new devices with multiple
-screens <em>and</em> existing devices running older platform versions. You
-should be able to make these changes to your application such that you can
-distribute a single {@code .apk} to all devices.</p>
-
-<p>The recommended strategy is to develop against the most recent version of the
-platform you are targeting, and test on the minimum platform version you want to run on.
-Here's how to do that:</p>
+<p>To better understand how you can support multiple densities when manipulating graphics at
+runtime, you should understand that the system helps ensure the proper scale for bitmaps in the
+following ways:</p>
<ol>
- <li>Maintain compatibility with existing devices by leaving your application's
-<code>android:minSdkVersion</code> attribute as it is. You <em>do not</em> need
-to increment the value of the attribute to support new devices and multiple
-screens. </li>
- <li>Extend compatibility for Android 1.6 (and higher) devices by adding
-a new attribute — <code>android:targetSdkVersion</code> — to the
-<code>uses-sdk</code> element. Set the value of the attribute to
-<code>"4"</code>. [To support <em>xhdpi</em> and <em>xlarge</em> screens, set the value to
-<code>"9"</code>.] This allows your application to "inherit" the platform's
-multiple screens support, even though it is technically using an earlier version
-of the API. </li>
- <li>Add an empty <code><supports-screens></code> element as a child of
-<code><manifest></code>. If you need to enable size or density attributes
-later, this is where you will add them.</li>
- <li>Change your application's build properties, such that it compiles against
-the Android 1.6 (API Level 4) library [or against Android 2.3 (API Level 9) to support
-<em>xhdpi</em> and <em>xlarge</em> screens], rather than against the Android 1.5 (or
-earlier) library. You will not be able to compile your application against the
-older platform because of the new manifest attribute. </li>
- <li>Set up AVDs for testing your application on Android 1.6 [or Android 2.3] and higher
-releases. Create AVDs that use the screen sizes and densities that you want to
-support. When you create the AVDs, make sure to select the Android 1.6 [or Android 2.3] or higher
-platform as the system image to run. For more information, see <a
-href="#testing">How to Test Your Application on Multiple Screens</a>,
-below.</li>
- <li>Set up AVDs for testing your application on older versions of the platform, as low as the
-version declared by your <code>android:minSdkVersion</code>. You need AVDs running the older
-platforms you are targeting, so that
-you can test for compatibility and ensure that there are no functional
-regressions. </li>
- <li>Compile your application against the Android 1.6 [or Android 2.3] library and run it on the
-AVDs you created. Observe the way your application looks and runs, and test all
-of the user interactions. </li>
- <li>Debug any display or functional issues. For issues that you resolve in
-your application code, <span style="color:red">make certain not to use any APIs
-introduced later than the version declared by your <code>android:minSdkVersion</code></span>. If you
-are in doubt, refer to SDK reference documentation and look for the API Level specifier for the API
-you want to use. Using newer APIs not supported by your minimum version will mean that your
-application will no longer be compatible with devices running on that version.</li>
- <li>For resource-related issues, you can try resolving them by:
- <ul>
- <li>Adding a <code>anyDensity="false"</code> attribute to
-<code><supports-screens></code>, to enable density-compatibility
-scaling.</li>
- <li>Creating any size- or density-specific resources you need and placing
-them in directories tagged with the <a href="#qualifiers">correct
-qualifiers</a>. Qualifiers must be arranged in a proscribed order. See
-<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">
-Providing Alternative Resources</a> for more information. </li>
- <li>Note that if you add size- or density-specific resource directories
-tagged with any of the resource qualifiers listed in this document, you should
-make sure to also tag those directories with the <code>v<api-level></code>
-qualifier (for example, <code>-v4</code> to target API Level 4). This ensures that those resources
-will be ignored when the application is run on Android 1.5 or lower platform
-versions.</p></li>
- </ul>
- </li>
- <li>If your application does not offer support (such as custom layouts) for
-large screens and you want the platform to display your application in
-screen-compatibility mode on larger screens, add the
-<code>largeScreens="false"</code> and <code>xlargeScreens="false"</code> attributes to the
-<code><supports-screens></code> element in the manifest. See
-<a href="#compatibility-examples">Screen-Compatibility Examples</a> for
-illustrations of how the platform displays your application in this case.</li>
- <li>If your application does not offer support (such as custom layouts) for
-small screens (such as on a QVGA low-density screen) and you do not want Android
-Market to offer the application to users of small-screen devices, you
-<em>must</em> add a <code>smallScreens="false"</code> attribute to the
-<code><supports-screens></code> element. </li>
- <li>Continue testing and debugging until your application performs as expected
-on all of the platforms and screen sizes your application will support.</li>
- <li>Export, zipalign, and sign your application using the same private key you
-used when publishing the previous version, then publish the application to users
-as an update. </li>
+<li><em>Pre-scaling of resources (such as bitmap drawables)</em>
+
+ <p>Based on the density of the current screen, the system uses any size- or density-specific
+resources from your application and displays them without scaling. If resources are not available in
+the correct density, the system loads the default resources and scales them up or down as needed to
+match the current screen's density. The system assumes that default resources (those from a
+directory without configuration qualifiers) are designed for the baseline screen density (mdpi),
+unless they are loaded from a density-specific resource directory. Pre-scaling is, thus, what the
+system does when resizing a bitmap to the appropriate size for the current screen
+density.</p>
+
+ <p>If you request the dimensions of a pre-scaled resource, the system returns values
+representing the dimensions <em>after</em> scaling. For example, a bitmap designed at 50x50 pixels
+for an mdpi screen is scaled to 75x75 pixels on an hdpi screen (if there is no alternative resource
+for hdpi) and the system reports the size as such.</p>
+
+<p>There are some situations in which you might not want Android to pre-scale
+a resource. The easiest way to avoid pre-scaling is to put the resource in a resource directory
+with the {@code nodpi} configuration qualifier. For example:</p>
+
+<pre class="classic">res/drawable-nodpi/icon.png</pre>
+
+<p>When the system uses the {@code icon.png} bitmap from this folder, it does not scale it
+based on the current device density.</p>
+</li>
+
+<li><em>Auto-scaling of pixel dimensions and coordinates</em>
+
+ <p>An application can disable pre-scaling by setting <a
+href="{@docRoot}guide/topics/manifest/supports-screens-element.html#any">{@code
+android:anyDensity}</a> to {@code "false"} in the manifest or programmatically for a {@link
+android.graphics.Bitmap} by setting {@link android.graphics.BitmapFactory.Options#inScaled} to
+{@code "false"}. In this case, the system auto-scales any absolute pixel coordinates and pixel
+dimension values at draw time. It does this to ensure that pixel-defined screen elements are still
+displayed at approximately the same physical size as they would be at the baseline screen density
+(mdpi). The system handles this scaling transparently to the application and reports the scaled
+pixel dimensions to the application, rather than physical pixel dimensions.</p>
+
+ <p>For instance, suppose a device has a WVGA high-density screen, which is 480x800 and about the
+same size as a traditional HVGA screen, but it's running an application that has disabled
+pre-scaling. In this case, the system will "lie" to the application when it queries for screen
+dimensions, and report 320x533 (the approximate mdpi translation for the screen density). Then, when
+the application does drawing operations, such as invalidating the rectangle from (10,10) to (100,
+100), the system transforms the coordinates by scaling them the appropriate amount, and actually
+invalidate the region (15,15) to (150, 150). This discrepancy may cause unexpected behavior if
+your application directly manipulates the scaled bitmap, but this is considered a reasonable
+trade-off to keep the performance of applications as good as possible. If you encounter this
+situation, read the following section about <a href="#dips-pels">Converting dp units to pixel
+units</a>.</p>
+
+ <p>Usually, <strong>you should not disable pre-scaling</strong>. The best way to support multiple
+screens is to follow the basic techniques described above in <a href="#support">How to Support
+Multiple Screens</a>.<p>
+</li>
+
</ol>
-<p>In particular, remember to test your application on an AVD that emulates a
-small-screen device. Devices that offer screens with QVGA resolution at low
-density are available now. Users of those devices may want to download your
-application, so you should understand how your application will look and
-function on a small-screen device. In many cases, the reduced screen area and
-density mean that you may need to make tradeoffs in design, content, and
-function on those devices. </p>
-<p>Also give extra attention to testing your application on an AVD that emulates an <em>xlarge</em>
-screen. Devices with extra large screens
-are tablet-sized or larger, so you should pay close attention to how usable your application is on
-such screens. You might want to design new layouts specifically for extra large screens, to address
-usability aspects such as the location and size of buttons in your UI. To test your application on
-an extra large screen, create an AVD targeted to Android 2.3 with a high resolution, such as 1280 x
-800, and the default density of 160dpi. This AVD will use any resources you've provided with the
-<code>xlarge</code> <a href="#qualifiers">resouce qualifier</a>.</p>
+<p>If your application manipulates bitmaps or directly interacts with pixels on the screen in some
+other way, you might need to take additional steps to support different screen densities. For
+example, if you respond to touch gestures by counting the number of pixels that a finger
+crosses, you need to use the appropriate density-independent pixel values, instead of actual
+pixels.</p>
+
+
+<h3 id="scaling">Scaling Bitmap objects created at runtime</h3>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/screens_support/scale-test.png" alt="" />
+<p class="img-caption"><strong>Figure 5.</strong> Comparison of pre-scaled and auto-scaled
+bitmaps, from <a
+href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html">
+ApiDemos</a>.
+</p>
+</div>
+
+<p>If your application creates an in-memory bitmap (a {@link android.graphics.Bitmap} object), the
+system assumes that the bitmap is designed for the baseline medium-density screen, by default, and
+auto-scales the bitmap at draw time. The system applies "auto-scaling" to a {@link
+android.graphics.Bitmap} when the bitmap has unspecified density properties. If you don't properly
+account for the current device's screen density and specify the bitmap's density properties, the
+auto-scaling can result in scaling artifacts the same as when you don't provide alternative
+resources.</p>
+
+<p>To control whether a {@link android.graphics.Bitmap} created at runtime is scaled or not, you can
+specify the density of the bitmap with {@link android.graphics.Bitmap#setDensity setDensity()},
+passing a density constant from {@link android.util.DisplayMetrics}, such as {@link
+android.util.DisplayMetrics#DENSITY_HIGH} or {@link android.util.DisplayMetrics#DENSITY_LOW}.</p>
+
+<p>If you're creating a {@link android.graphics.Bitmap} using {@link
+android.graphics.BitmapFactory}, such as from a file or a stream, you can use {@link
+android.graphics.BitmapFactory.Options BitmapFactory.Options} to define properties of the bitmap as
+it already exists, which determine if or how the system will scale it. For example, you can use the
+{@link android.graphics.BitmapFactory.Options#inDensity} field to define the density for which the
+bitmap is designed and the {@link
+android.graphics.BitmapFactory.Options#inScaled} field to specify whether the bitmap should scale to
+match the current device's screen density.</p>
+
+<p>If you set the {@link
+android.graphics.BitmapFactory.Options#inScaled} field to {@code false}, then you disable any
+pre-scaling that the system may apply to the bitmap and the system will then auto-scale it at draw
+time. Using auto-scaling instead of pre-scaling can be more CPU expensive, but uses
+less memory.</p>
+
+<p>Figure 5 demonstrates the results of the pre-scale and auto-scale mechanisms when loading low
+(120), medium (160) and high (240) density bitmaps on a high-density screen. The differences are
+subtle, because all of the bitmaps are being scaled to match the current screen density, however the
+scaled bitmaps have slightly different appearances depending on whether they are pre-scaled or
+auto-scaled at draw time. You can find the source code for this sample application, which
+demonstrates using pre-scaled and auto-scaled bitmaps, in <a
+href="resources/samples/ApiDemos/src/com/example/android/apis/graphics/DensityActivity.html">
+ApiDemos</a>.</p>
+
+<p class="note"><strong>Note:</strong> In Android 3.0 and above, there should be no perceivable
+difference between pre-scaled and auto-scaled bitmaps, due to improvements in the graphics
+framework.</p>
+
+
+
+
+
+<h3 id="dips-pels">Converting dp units to pixel units</h3>
+
+<p>In some cases, you will need to express dimensions in <code>dp</code> and then convert them to
+pixels. Imagine an application in which a scroll or fling gesture is recognized after the user's
+finger has moved by at least 16 pixels. On a baseline screen, a user's must move by {@code 16 pixels
+/ 160 dpi}, which equals 1/10th of an inch (or 2.5 mm) before the gesture is recognized. On a device
+with a high density display (240dpi), the user's must move by {@code 16 pixels / 240 dpi}, which
+equals 1/15th of an inch (or 1.7 mm). The distance is much shorter and the application thus appears
+more sensitive to the user.</p>
+
+<p>To fix this issue, the gesture threshold must be expressed in code in <code>dp</code> and then
+converted to actual pixels. For example:</p>
+
+<pre>// The gesture threshold expressed in dp
+private static final float GESTURE_THRESHOLD_DP = 16.0f;
+
+// Get the screen's density scale
+final float scale = {@link android.content.ContextWrapper#getResources getResources()}.{@link
+android.content.res.Resources#getDisplayMetrics getDisplayMetrics()}.density;
+// Convert the dps to pixels, based on density scale
+mGestureThreshold = (int) (GESTURE_THRESHOLD_DP * scale + 0.5f);</span>
+
+// Use mGestureThreshold as a distance in pixels...
+</pre>
+
+<p>The {@link android.util.DisplayMetrics#density DisplayMetrics.density} field specifies the scale
+factor you must use to convert {@code dp} units to pixels, according to the current screen density.
+On a medium-density screen, {@link android.util.DisplayMetrics#density DisplayMetrics.density}
+equals 1.0; on a high-density screen it equals 1.5; on an extra high-density screen, it equals 2.0;
+and on a low-density screen, it equals 0.75. This figure is the factor by which you should multiply
+the {@code dp} units on order to get the actual pixel count for the current screen. (Then add {@code
+0.5f} to round the figure up to the nearest whole number, when converting to an integer.) For more
+information, refer to the {@link android.util.DisplayMetrics DisplayMetrics} class.</p>
+
+<p>However, instead of defining an arbitrary threshold for this kind of event, you should
+use pre-scaled configuration values that are available from {@link
+android.view.ViewConfiguration}.</p>
+
+
+<h4 id="pre-scaled-values">Using pre-scaled configuration values</h4>
+
+<p>You can use the {@link android.view.ViewConfiguration} class to access common distances,
+speeds, and times used by the Android system. For instance, the
+distance in pixels used by the framework as the scroll threshold can be obtained with {@link
+android.view.ViewConfiguration#getScaledTouchSlop()}:</p>
+
+<pre>
+private static final int GESTURE_THRESHOLD_DP = ViewConfiguration.get(myContext).getScaledTouchSlop();
+</pre>
+
+<p>Methods in {@link android.view.ViewConfiguration} starting with the <code>getScaled</code> prefix
+are guaranteed to return a value in pixels that will display properly regardless of the current
+screen density.</p>
+
+
+
+
<h2 id="testing">How to Test Your Application on Multiple Screens</h2>
-<p>Before publishing an application that supports multiple screens, you should
-thoroughly test it in all of the targeted screen sizes and densities. You can
-test how it displays with the platform's compatibility features enabled or with
-screen-specific UI resources included in your application. The Android SDK
-includes all the tools you need to test your application on any supported
-screen.</p>
-
-<!-- You can test in any minsdk, and you can test with compatabiltiy code or
-not. Once you've tested your application and found that it displays properly on
-various screen sizes, you should make sure to add the corresponding size
-attribute(s) to your application's manifest. -->
-
-<div id="f9.5" class="figure" style="width:530px">
- <img src="{@docRoot}images/screens_support/avds-config.png" />
- <p class="img-caption"><strong>Figure 4.</strong>
- A typical set of AVDs for testing screens support.</p>
+<div class="figure" style="width:500px;margin:0">
+ <img src="{@docRoot}images/screens_support/avds-config.png" alt="" />
+ <p class="img-caption"><strong>Figure 6.</strong>
+ A set of AVDs for testing screens support.</p>
</div>
-<p>As a test environment for your applications, set up a series of AVDs that
-emulate the screen sizes and densities you want to support. The Android SDK
-includes several emulator skins to get you started. You can use the Android AVD
-Manager or the <code>android</code> tool to create AVDs that use the various
-emulator skins and you can also set up custom AVDs to test densities other than
-the defaults. For general information about working with AVDs, see
-<a href="{@docRoot}guide/developing/devices/index.html">Creating and Managing Virtual
-Devices</a>.</p>
+<p>Before publishing your application, you should thoroughly test it in all of the supported screen
+sizes and densities. The Android SDK includes emulator skins you can use, which
+replicate the sizes and densities of common screen configurations on which your application is
+likely to run. You can also modify the default size, density, and resolution of the emulator skins
+to replicate the characteristics of any specific screen. Using the emulator skins and additional
+custom configurations allows you to test any possible screen configuration, so you don't
+have to buy various devices just to test your application's screen support.</p>
-<p>The Android SDK provides a set of default emulator skins that you can use for
-testing. The skins are included as part of each Android platform that you can
-install in your SDK. The Android 1.6 platform offers these default skins:</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>
-<ul>
- <li>
- QVGA (240x320, low density, small screen)
- </li>
- <li>
- HVGA (320x480, medium density, normal screen)
- </li>
- <li>
- WVGA800 (480x800, high density, normal screen)
- </li>
- <li>
- WVGA854 (480x854 high density, normal screen)
- </li>
-</ul>
+<p>To launch the Android SDK and AVD 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>
-<p>The Android 2.0 platform offers all of the Android 1.6 default skins,
-above, plus:</p>
+<p>Table 2 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>
-<ul>
- <li>
- WQVGA400 (240x400, low density, normal screen)
- </li>
- <li>
- WQVGA432 (240x432, low density, normal screen)
- </li>
-</ul>
+<p>For more information about creating and using AVDs to test your application, see <a
+href="{@docRoot}guide/developing/devices/managing-avds.html">Managing AVDs with AVD
+Manager</a>.</p>
-<p>If you are using the <code>android</code> tool command line to create your
-AVDs, here's an example of how to specify the skin you want to use:</p>
-<pre>android create avd ... --skin WVGA800</pre>
+<p class="table-caption" id="screens-table"><strong>Table 2.</strong> Various screen
+configurations available from emulator skins in the Android SDK (indicated in bold) and other
+representative resolutions.</p>
+
+ <table class="normal-headers">
+ <tbody>
+ <tr>
+ <th></th>
+ <th>
+ <nobr>Low density (120), <em>ldpi</em></nobr>
+ </th>
+ <th>
+ <nobr>Medium density (160), <em>mdpi</em></nobr>
+ </th>
+ <th>
+ <nobr>High density (240), <em>hdpi</em><nobr>
+ </th>
+ <th>
+ <nobr>Extra high density (320), <em>xhdpi</em><nobr>
+ </th>
+ </tr>
+ <tr>
+ <th>
+ <em>Small</em> screen
+ </th>
+ <td><strong>QVGA (240x320)</strong></td>
+ <td></td>
+ <td>480x640</td>
+ <td></td>
+ </tr>
+ <tr>
+ <th>
+ <em>Normal</em> screen
+ </th>
+ <td><strong>WQVGA400 (240x400)</strong>
+ <br><strong>WQVGA432 (240x432)</strong></td>
+ <td><strong>HVGA (320x480)</strong></td>
+ <td><strong>WVGA800 (480x800)</strong>
+ <br><strong>WVGA854 (480x854)</strong>
+ <br>600x1024</td>
+ <td>640x960</td>
+ </tr>
+ <tr>
+ <th>
+ <em>Large</em> screen
+ </th>
+ <td><strong>WVGA800** (480x800)</strong>
+ <br><strong>WVGA854** (480x854)</strong></td>
+ <td><strong>WVGA800* (480x800)</strong>
+ <br><strong>WVGA854* (480x854)</strong>
+ <br>600x1024</td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <th>
+ <em>Extra Large</em> screen
+ </th>
+ <td>1024x600</td>
+ <td><strong>WXGA (1280x800)</strong><sup>†</sup><br>
+ 1024x768<br>1280x768</td>
+ <td>1536x1152<br>1920x1152
+ <br>1920x1200</td>
+ <td>2048x1536<br>2560x1536
+ <br>2560x1600</td>
+ </tr>
+ <tr>
+ <td colspan="5" style="border:none;font-size:85%;">* To emulate this configuration, specify a
+custom density of 160 when creating an AVD that uses a WVGA800 or WVGA854 skin.<br/>
+ ** To emulate this configuration, specify a custom density of 120 when creating an AVD that
+uses a WVGA800 or WVGA854 skin.<br/>
+ † This skin is available with the Android 3.0 platform
+ </td>
+ </tr>
+</table>
+
+<p>To see the relative numbers of active devices that support any given screen configuration, see
+the <a href="{@docRoot}resources/dashboard/screens.html">Screen Sizes and Densities</a>
+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
+Manager.</p>
+</div>
<p>We also recommend that you test your application in an emulator that is set
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 resolutions and densities. To
-do so you will need to know the approximate density, in dpi, of your computer
-monitor (a 30" Dell monitor has for instance a density of about 96 dpi.). Use
-your monitor's dpi as the value of the <code>-scale</code> option, when
-launching the emulator, for example:</p>
-
-<pre>emulator -avd <name> -scale 96dpi</pre>
-
-<p>If you are working in Eclipse with ADT, you can specify the <code>-scale
-96dpi</code> option in the Target tab of run and debug configurations, under
-"Additional Emulator Command Line Options" field. </p>
-
-<p>Note that starting the emulator with the <code>-scale</code> option will
-scale the entire emulator display, based on both the dpi of the skin and of your
-monitor. The default emulator skins included in the Android SDK are listed
-in <a href="#screens-table">Table 1</a>, earlier in this document.</p>
-
-<div class="figure" style="width:324px">
- <img src="{@docRoot}images/screens_support/avd-density.png" >
- <p class="img-caption"><strong>Figure 5.</strong>
- Resolution and density options that you can use, when creating an AVD using the AVD Manager.</p>
-</div>
-
-<p>You should also make sure to test your application on different physical
-screen sizes within a single size-density configuration. For example, to
-display this screen configuration on a 30" monitor you will need to adjust
-the value passed to <code>-scale</code> to 96*2.8/3.3 = 81dpi. You can also
-pass a float value to <code>-scale</code> to specify your own scaling factor:</p>
-
-<pre>emulator -avd <name> -scale 0.6</pre>
+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
+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 either adjust an
-existing skin, or create an AVD that uses a custom resolution or density.</p>
+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,
+instead of selecting a Built-in Skin.</p>
-<p>In the AVD Manager, you can specify a custom skin resolution or density in
-the Create New AVD dialog, as shown in Figure 5, at right.</p>
+<p>If you are launching your AVD from the command line, you can specify the scale for
+the emulator with the <code>-scale</code> option. For example:</p>
-<p>In the <code>android</code> tool, follow these steps to create an AVD with a
-custom resolution or density:</p>
+<pre>emulator -avd <avd_name> -scale 96dpi</pre>
-<ol>
- <li>Use the <code>create avd</code> command to create a new AVD, specifying
-the <code>--skin</code> option with a value that references either a default
-skin name (such as "WVGA800") or a custom skin resolution (such as 240x432).
-Here's an example:
- <pre>android create avd -n <name> -t <targetID> --skin WVGA800</pre>
- </li>
- <li>To specify a custom density for the skin, answer "yes" when asked whether
-you want to create a custom hardware profile for the new AVD.</li>
- <li>Continue through the various profile settings until the tool asks you to
-specify "Abstracted LCD density" (<em>hw.lcd.density</em>). Enter an appropriate
-value, such as "120" for a low-density screen, "160" for a medium density screen,
-or "240" for a high-density screen.</li>
- <li>Set any other hardware options and complete the AVD creation.</li>
-</ol>
+<p>To refine the size of the emulator, you can instead pass the {@code -scale} option a number
+between 0.1 and 3 that represents the desired scaling factor.</p>
-<p>In the example above (WVGA medium density), the new AVD will emulate a 5.8"
-WVGA screen.</p>
-
-<p>As an alternative to adjusting the emulator skin configuration, you can use
-the emulator skin's default density and add the <code>-dpi-device</code> option
-to the emulator command line when starting the AVD. For example, </p>
-
-<pre>emulator -avd WVGA800 -scale 96dpi -dpi-device 160</pre>
-
-
-<h2 id="compatibility-examples">Screen-Compatibility Examples</h2>
-
-<p>This section provides examples of how the Android platform displays an
-application written for the baseline screen configuration — HVGA (320x480)
-resolution on a 3.2" screen — with all of the platform's size- and
-density-compatibility features enabled. That is, the examples show how
-the platform displays an application that doesn't provide built-in support
-for the screen on which it is being rendered, but which instead relies completely
-on the platform.</p>
-
-<p>The platform's screen-compatibility features are designed to provide such
-an application with a virtual baseline screen environment against which to run,
-while at the same time ensuring for the user a physical display that is
-approximately the same as the baseline screen size and density. </p>
-
-<p>Legacy applications that have not been modified to support multiple
-screens would be typical examples of such applications. In most cases,
-you would want to add multiple-screens support to a legacy application and
-publish an updated version, as described in <a href="#strategies">Strategies
-for Legacy Applications</a>. However, if you did not do so, the
-platform still performs best-effort rendering of your application, as
-illustrated below.</p>
-
-<p> Internally, these are the compatibility features that the platform
-provides, based on the current device screen:</p>
-
- <ul>
- <li>
- If the device's screen density is <em>not medium</em>, the application's
-layout and drawing of its content is as if the screen <em>is</em> medium density, but the
-framework scales the layout and images (if the image for the target density is
-not available) to fit the target density. It scales 1.5 times if the target
-density is high density (160->240 virtual dpi), or 0.75 times if the target
-density is low density (160 -> 120 virtual dpi).
- </li>
- <li>
- If the device's screen size is <em>small</em>, there are few options
-options for making Android 1.5 applications work well on such a screen, so
-Android Market will filter applications that are not known to support these
-screens from the device.
- </li>
- <li>
- If the device's screen size is <em>large</em>, it limits the application's
-screen to the normal size and draws a black background around the application.
-For example, if an application supports high density, but does not support large
-screens, it only uses a 480x720 area of the screen and the rest will be filled
-with a black background (see example below).
- </li>
- </ul>
-
-<table style="width:10%;margin-left:.5em;">
- <tr>
- <td>
- HVGA, normal size, normal density<br>
- [ emulator -skin HVGA ]<br>
- <img height=149 src="{@docRoot}images/screens_support/afdvfckr9j_15dcsvrscg_b.png" width=225>
- </td>
- <td>
- WVGA, normal size, high density<br>
- [emulator -skin WVGA854 -dpi-device 240]<br>
- <img height=143 src="{@docRoot}images/screens_support/afdvfckr9j_18c6mhm3cm_b.png" width=254><br>
- <p>The application occupies full screen as its considered to be normal size. (close to 480x720)</p>
- </td>
- </tr>
- <tr>
- <td>
- VGA, large size, medium density<br>
- [ emulator -skin 640x480 ]<br>
- <img height=243 src="{@docRoot}images/screens_support/afdvfckr9j_14fj6dhsc3_b.png" width=324>
- <p>The application occupies 320x480 of VGA.</p>
- </td>
- <td>
- SVGA, large size, high density<br>
- [ emulator -skin 800x600 -dpi-device 240]<br>
- <img height=223 src="{@docRoot}images/screens_support/afdvfckr9j_19c743p6cr_b.png" width=294>
- <p>The application occupies 480x720 (=1.5 x [320x480]) of 800x600.</p>
- </td>
- </tr>
-</table>
-
-
-<h3>Screen-compatibility limitations on small, low-density screens</h3>
-
-<p>Because these device has smaller state/resolution, there are known
-limitations when application runs in compatibility mode.</p>
-
-<h4>QVGA</h4>
-
-<p>Because QVGA (240x320) screens have less screen area available and lower
-density than normal, which is 240x360 in low density, some applications cannot
-render all their content properly on those screens. As a result, on a QVGA
-device, Android Market will filter out all applications that do not declare they
-support small screens.</p>
-
-<p>Examples:</p>
-
-<table style="width:10%;margin-left:.5em;">
- <tr>
- <td>The part of z value graph is chopped.</td>
- <td>The lap time area is chopped.<br></td>
- </tr>
- <tr>
- <td><img height=207 src="{@docRoot}images/screens_support/afdvfckr9j_16g95wjqg3_b.png" width="155"></td>
- <td><img height=186 src="{@docRoot}images/screens_support/afdvfckr9j_17p2w4txgc_b.png" width="139"></td>
- </tr>
-</table>
-
-
-<h4>Images with 1 pixel height/width.</h4>
-
-<p>If an image has 1 pixel height or width, it may not be shown on the screen
-due to rounding issue. This is inevitable as it just does not have enough
-pixels.</p>
-
-<p>For example, in the screen below, the divider in the menu is invisible
-because the width of the image is trancated to 0. (This particular problem is
-solvable because menu is handled inside framework, but there is no generic
-solution as it just does not have enough pixels.)</p>
-
-<img height=222 src="{@docRoot}images/screens_support/afdvfckr9j_20fvptbbdd_b.png" width=166>
-
-
-
+<p>For more information about creating AVDs from the command line, see <a
+href="{@docRoot}guide/developing/devices/managing-avds-cmdline.html">Managing AVDs from the
+Command Line</a></p>
diff --git a/docs/html/guide/topics/resources/providing-resources.jd b/docs/html/guide/topics/resources/providing-resources.jd
index 7c84bd2..caebe55 100644
--- a/docs/html/guide/topics/resources/providing-resources.jd
+++ b/docs/html/guide/topics/resources/providing-resources.jd
@@ -461,8 +461,8 @@
to match the device density.</li>
</ul>
<p><em>Added in API Level 4.</em></p>
- <p>There is thus a 3:4:6 scaling ratio between the three densities, so a 9x9 bitmap
- in ldpi is 12x12 in mdpi and 18x18 in hdpi.</p>
+ <p>There is thus a 3:4:6:8 scaling ratio between the four densities, so a 9x9 bitmap
+ in ldpi is 12x12 in mdpi, 18x18 in hdpi and 24x24 in xhdpi.</p>
<p>When Android selects which resource files to use,
it handles screen density differently than the other qualifiers.
In step 1 of <a href="#BestMatch">How Android finds the best
diff --git a/docs/html/guide/topics/usb/adk.jd b/docs/html/guide/topics/usb/adk.jd
new file mode 100644
index 0000000..44d7fc2
--- /dev/null
+++ b/docs/html/guide/topics/usb/adk.jd
@@ -0,0 +1,849 @@
+page.title=Android Open Accessory Development Kit
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li>
+ <a href="#getting-started">Getting Started with the ADK</a>
+
+ <ol>
+ <li><a href="#installing">Installing the Arduino software and necessary
+ libraries</a></li>
+
+ <li><a href="#installing-firmware">Installing the firmware to the ADK board</a></li>
+
+ <li><a href="#running-demokit">Running the DemoKit Android application</a></li>
+
+ <li><a href="#monitoring">Monitoring the ADK board</a></li>
+ </ol>
+ </li>
+
+ <li>
+ <a href="#how">How an Accessory Communicates with an Android-powered Device in Accessory
+ Mode</a>
+
+ <ol>
+ <li><a href="#wait">Wait for and detect connected devices</a></li>
+
+ <li><a href="#determine">Determine the connected device's accessory mode
+ support</a></li>
+
+ <li><a href="#start">Attempt to start the device in accessory mode</a></li>
+
+ <li><a href="#establish">Establish communication with the device</a></li>
+ </ol>
+ </li>
+
+ <li>
+ <a href="#firmware">How the ADK board communicates with an Android-powered Device in
+ Accessory Mode</a>
+
+ <ol>
+ <li><a href="#wait-adk">Wait for and detect connected devices</a></li>
+
+ <li><a href="#determine-adk">Determine the connected device's accessory mode
+ support</a></li>
+
+ <li><a href="#start-adk">Attempt to start the device in accessory mode</a></li>
+
+ <li><a href="#establish-adk">Establish communication with the device</a></li>
+ </ol>
+ </li>
+ </ol>
+
+ <h2>Where to Buy</h2>
+
+ <ol>
+ <li><a href=
+ "http://www.rt-shop.sakura.ne.jp/rt-shop/index.php?main_page=product_info&products_id=2731&language=en">
+ RT Corp</a></li>
+
+ <li><a href=
+ "http://www.microchip.com/android">
+ Microchip</a></li>
+ </ol>
+ </div>
+ </div>
+
+ <p>The Android 3.1 platform (also backported to Android 2.3.4) introduces Android Open Accessory
+ support, which allows external USB hardware (an Android USB accessory) to interact with an
+ Android-powered device in a special "accessory" mode. When an Android-powered powered device is
+ in accessory mode, the connected accessory acts as the USB host (powers the bus and enumerates
+ devices) and the Android-powered device acts as the device. Android USB accessories are
+ specifically designed to attach to Android-powered devices and adhere to a simple protocol
+ (Android accessory protocol) that allows them to detect Android-powered devices that support
+ accessory mode. Accessories must also provide 500mA at 5V for charging power. Many previously
+ released Android-powered devices are only capable of acting as a USB device and cannot initiate
+ connections with external USB devices. Android Open Accessory support overcomes this limitation
+ and allows you to build accessories that can interact with an assortment of Android-powered
+ devices by allowing the accessory initiate the connection.</p>
+
+ <p class="note"><strong>Note:</strong> Accessory mode is ultimately dependent on the device's
+ hardware and not all devices will support accessory mode. Devices that support accessory mode can
+ be filtered using a <code><uses-feature></code> element in your corresponding application's
+ Android manifest. For more information, see the <a href=
+ "{@docRoot}guide/topics/usb/accessory.html#manifest">USB Accessory</a> Developer Guide.</p>
+
+ <p>The Android Open Accessory Development Kit (ADK) provides an implementation of an Android USB
+ accessory that is based on the <a href="http://www.arduino.cc/">Arduino open source electronics
+ prototyping platform</a>, the accessory's hardware design files, code that implements the
+ accessory's firmware, and the Android application that interacts with the accessory. The hardware
+ design files and code are contained in the <a href=
+ "https://dl-ssl.google.com/android/adk/adk_release_0506.zip">ADK package download</a>. You can
+ <a href=
+ "http://www.rt-shop.sakura.ne.jp/rt-shop/index.php?main_page=product_info&products_id=2731&language=en">buy
+ the hardware components</a> of the ADK if you do not already have them. There is also a <a href=
+ "http://www.microchip.com/android">
+ PIC based USB microcontroller</a> that is not based on the ADK design, but that you can still use
+ to create your own Android open accessories. We expect more hardware distributers to create a
+ variety of kits, so please stay tuned for further developments.</p>
+
+ <p>The main hardware and software components of the ADK include:</p>
+
+ <ul>
+ <li>A USB micro-controller board that is based on the Arduino Mega2560 and Circuits@Home USB
+ Host Shield designs (now referred to as the ADK board), which you will later implement as an
+ Android USB accessory. The ADK board provides input and output pins that you can implement
+ through the use of attachments called "shields." Custom firmware, written in C++, is installed
+ on the board to define the board's functionality and interaction with the attached shield and
+ Android-powered device. The hardware design files for the board are located in
+ <code>hardware/</code> directory.</li>
+
+ <li>An Android Demo Shield (ADK shield) that affixes atop the ADK board implements the input
+ and output points on the board. These implementations include a joystick, LED outputs, and
+ temperature and light sensors. You can create or buy your own shields or wire your own features
+ to the ADK board to implement custom functionality. The hardware design files for the shield
+ are located in <code>hardware/</code>.</li>
+
+ <li>A library based on the <a href=
+ "http://www.circuitsathome.com/arduino_usb_host_shield_projects">Arduino USB Host Shield</a>
+ library provides the logic for the USB micro-controller board to act as a USB Host. This allows
+ the board to initiate transactions with USB devices. Describing how to use this entire library
+ is out of the scope of this document. Where needed, this document points out important
+ interactions with the library. For more information, see the source code for the Arduino USB
+ Host Shield library in the <code>firmware/arduino_libs/USB_Host_Shield</code> directory.</li>
+
+ <li>An Arduino sketch, <code>firmware/demokit/demokit.pde</code>, defines the firmware that
+ runs on the ADK board and is written in C++. The sketch calls the Android accessory protocol
+ library to interact with the Android-powered device. It also sends data from the ADK board and
+ shield to the Android application and receives data from the Android application and outputs it
+ to the ADK board and shield.</li>
+
+ <li>The Android accessory protocol library, which is located in the
+ <code>firmware/arduino_libs/AndroidAccessory</code> directory. This library defines how to
+ enumerate the bus, find a connected Android-powered device that supports accessory mode, and
+ how to setup communication with the device.</li>
+
+ <li>Other third party libraries to support the ADK board's functionality:
+
+ <ul>
+ <li><a href="http://www.arduino.cc/playground/Main/CapSense">CapSense library</a></li>
+
+ <li><a href="http://www.arduino.cc/playground/Learning/I2C">I2C / TWI (Two-Wire Interface)
+ library</a></li>
+
+ <li><a href="http://www.arduino.cc/playground/ComponentLib/Servo">Servo library</a></li>
+
+ <li><a href="http://www.arduino.cc/playground/Code/Spi">Spi library</a></li>
+
+ <li><a href="http://www.arduino.cc/en/Reference/Wire">Wire library</a></li>
+ </ul>
+ </li>
+
+ <li>An Android application, DemoKit, that communicates with the ADK board and shield. The
+ source for this project is in the <code>app/</code> directory.</li>
+ </ul>
+
+ <h2 id="getting-started">Getting Started with the ADK</h2>
+
+ <p>The following sections describe how to install the Arduino software on your computer, use the
+ Arduino software to install the ADK board's firmware, and install and run the accompanying
+ Android application for the ADK board. Before you begin, download the following items to set up
+ your development environment:</p>
+
+ <ul>
+ <li><a href="http://www.arduino.cc/en/Main/software">Arduino Software</a>: contains libraries
+ and an IDE for coding and installing firmware to the ADK board.</li>
+
+ <li><a href="http://www.arduino.cc/playground/Main/CapSense">CapSense library</a>: contains the
+ libraries to sense human capacitance. This is needed for the capacative button that is located
+ on the ADK shield.</li>
+
+ <li><a href="">The ADK package</a>: contains the firmware for the ADK board and hardware design
+ files for the ADK board and shield.</li>
+ </ul>
+
+ <h3 id="installing">Installing the Arduino software and necessary libraries</h3>
+
+ <p>To install the Arduino software:</p>
+
+ <ol>
+ <li>
+ <a href="http://arduino.cc/en/Guide/HomePage">Download and install</a> the Arduino Software
+ as described on the Arduino website.
+
+ <p class="note"><strong>Note:</strong> If you are on a Mac, install the FTDI USB Serial
+ Driver that is included in the Arduino package, even though the installation instructions say
+ otherwise.</p>
+ </li>
+
+ <li><a href="https://dl-ssl.google.com/android/adk/adk_release_0506.zip">Download</a> and
+ extract the ADK package to a directory of your choice. You should have an <code>app</code>,
+ <code>firmware</code>, and <code>hardware</code> directories.</li>
+
+ <li>Extract the CapSense download to a directory of your choice.</li>
+
+ <li>Install the necessary libraries:
+
+ <p>On Windows:</p>
+
+ <ol type="a">
+ <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and
+ <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories,
+ not just the files within) to the <code><arduino_installation_root>/libraries/</code>
+ directory.</li>
+
+ <li>Create a CapSense directory in the
+ <code><arduino_installation_root>/libraries/</code> directory</li>
+
+ <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense
+ download to the <code>CapSense</code> directory.</li>
+ </ol>
+
+ <p>On Mac:</p>
+
+ <ol type="a">
+ <li>Right-click on the Arduino application in Finder and select <strong>Show Package
+ Contents</strong>.</li>
+
+ <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and
+ <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories,
+ not just the files within) to the <code>Contents/Resources/Java/libraries</code> directory
+ inside the Arduino application.</li>
+
+ <li>Create a <code>CapSense</code> directory in the
+ <code>Contents/Resources/Java/libraries</code> directory.</li>
+
+ <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense
+ download to the <code>CapSense</code> directory.</li>
+ </ol>
+
+ <p>On Linux (Ubuntu):</p>
+
+ <ol type="a">
+ <li>Copy the <code>firmware/arduino_libs/AndroidAccessory</code> and
+ <code>firmware/arduino_libs/USB_Host_Shield</code> directories (the complete directories,
+ not just the files within) to the <code><arduino_installation_root>/libraries/</code>
+ directory.</li>
+
+ <li>Create a <code>CapSense</code> directory in the
+ <code><arduino_installation_root>/libraries/</code> directory.</li>
+
+ <li>Copy <code>CapSense.cpp</code> and <code>CapSense.h</code> from the unzipped CapSense
+ download to the <code>CapSense</code> directory.</li>
+
+ <li>Install the avr-libc library by entering <code>sudo apt-get install avr-libc</code>
+ from a shell prompt.</li>
+ </ol>
+ </li>
+ </ol>
+
+ <p>You should now have three new directories in the Arduino libraries directory:
+ <code>AndroidAccessory</code>, <code>USB_Host_Shield</code>, and <code>CapSense</code>.</p>
+
+ <h3 id="installing-firmware">Installing the firmware to the ADK board</h3>
+
+ <p>To install the firmware to the ADK board:</p>
+
+ <ol>
+ <li>Connect the ADK board to your computer using the micro-USB port, which allows two-way
+ communication and provides power to the ADK board.</li>
+
+ <li>Launch Arduino.</li>
+
+ <li>Click <strong>Tools > Board > Arduino Mega 2560</strong> to specify the ADK board's
+ type.</li>
+
+ <li>Select the appropriate USB port:
+
+ <ul>
+ <li>On Windows: click <strong>Tools > Serial Port > COM#</strong> to specify the port
+ of communication. The COM port number varies depending on your computer. COM1 is usually
+ reserved for serial port connections. You most likely want COM2 or COM3.</li>
+
+ <li>On Mac: Click <strong>Tools > Serial Port > dev/tty.usbserial-###</strong> to
+ specify the port of communication.</li>
+
+ <li>On Linux (Ubuntu): Click <strong>Tools > Serial Port > dev/ttyUSB#</strong> to
+ specify the port of communication.</li>
+ </ul>
+ </li>
+
+ <li>To open the firmware code (a sketch), click <strong>File > Open</strong> and select
+ <code>firmware/demokit/demokit.pde</code>.</li>
+
+ <li>Click <strong>Sketch > Compile/Verify</strong> to ensure that the sketch has no
+ errors.</li>
+
+ <li>Select <strong>File > Upload to I/O Board</strong>. When Arduino outputs <strong>Done
+ uploading.</strong>, the board is ready to communicate with your Android-powered device.</li>
+ </ol>
+
+ <h3 id="running-demokit">Running the DemoKit Android application</h3>
+
+ <p>The DemoKit Android application runs on your Android-powered device and communicates with the
+ ADK board. The ADK board receives commands such as lighting up the board's LEDs or sends data
+ from the board such as joystick movement and temperature readings.</p>
+
+ <p>To install and run the application in Eclipse:</p>
+
+ <ol>
+ <li><a href="http://code.google.com/android/add-ons/google-apis/installing.html">Install the
+ Google APIs API Level 10 add-on library</a>, which includes the Open Accessory library for
+ 2.3.4 devices that support accessory mode. This library is also forward compatible with Android
+ 3.1 or newer devices that support accessory mode. If you only care about Android 3.1 or newer
+ devices, all you need is API Level 12. For more information on deciding which API level to use,
+ see the <a href="{@docRoot}guide/topics/USB/accessory.html#choosing">USB Accessory</a>
+ documentation.</li>
+
+ <li>Click <strong>File > New > Project...</strong>, then select <strong>Android >
+ Android Project</strong></li>
+
+ <li>In the <strong>Project name:</strong> field, type DemoKit.</li>
+
+ <li>Choose <strong>Create project from existing source</strong>, click <strong>Browse</strong>,
+ select the <code>app</code> directory, and click <strong>Finish</strong>.</li>
+
+ <li>For Build Target, select <strong>Google APIs</strong> (Platform 2.3.3, API Level 10).
+
+ <p class="note"><strong>Note:</strong> Even though the add-on is labeled as
+ <strong>2.3.3</strong>, the newest Google API add-on library for API level 10 adds USB Open
+ Accessory API support for 2.3.4 devices.</p>
+ </li>
+
+ <li>Click <strong>Finish</strong>.</li>
+
+ <li>Install the application to your device.</li>
+
+ <li>Connect the ADK board (USB-A) to your Android-powered device (micro-USB). Ensure that the
+ power cable to the accessory is plugged in or that the micro-USB port on the accesory is
+ connected to your computer for power (this also allows you to <a href="monitoring">monitor the
+ ADK board</a>). When connected, accept the prompt that asks for whether or not to open the
+ DemoKit application to connect to the accessory. If the prompt does not show up, connect and
+ reconnect the accessory.</li>
+ </ol>
+
+ <p>You can now interact with the ADK board by moving the color LED or servo sliders (make sure
+ the servos are connected) or by pressing the relay buttons in the application. On the ADK shield,
+ you can press the buttons and move the joystick to see their outputs displayed in the
+ application.</p>
+
+ <h3 id="monitoring">Monitoring the ADK Board</h3>
+
+ <p>The ADK firmware consists of a few files that you should be looking at if you want to build
+ your own accessory. The files in the <code>firmware/arduino_libs/AndroidAccessory</code>
+ directory are the most important files and have the logic to detect and connect to
+ Android-powered devices that support accessory mode. Feel free to add debug statements (Arduino
+ <code>Serial.print()</code> statements) to the code located in the
+ <code>arduino_libraries_directory/AndroidAccessory</code> directory and
+ <code>firmware/demokit/demokit.pde</code> sketch and re-upload the sketch to the ADK board to
+ discover more about how the firmware works.</p>
+
+ <p>You can view the debug statements in the Arduino Serial Monitor by clicking <strong>Tools >
+ Serial Monitor</strong> and setting the baud to 115200. The following sections about how
+ accessories communicate with Android-powered devices describe much of what you should be doing in
+ your own accessory.</p>
+
+ <h2 id="how">How an Accessory Communicates with an Android-powered Device in Accessory Mode</h2>
+
+ <p>When you connect an accessory to an Android-powered device, the accessory's firmware must
+ carry out some standard steps to set up communication with the Android-powered device. If you are
+ building an accessory along with an application, this section goes over some general steps that
+ your firmware should carry out.</p>
+
+ <p>In general, an accessory should carry out the following steps:</p>
+
+ <ol>
+ <li>Wait for and detect connected devices</li>
+
+ <li>Determine the device's accessory mode support</li>
+
+ <li>Attempt to start the device in accessory mode if needed</li>
+
+ <li>Establish communication with the device if it supports the Android accessory protocol</li>
+ </ol>
+
+ <h3 id="wait">Wait for and detect connected devices</h3>
+
+ <p>Your accessory should have logic to continuously check
+ for connected Android-powered devices. When a device is connected, your accessory should
+ determine if the device supports accessory mode.</p>
+
+ <h3 id="determine">Determine the device's accessory mode support</h3>
+
+
+ <p>When an Android-powered device is connected, it can be in one of three states:</p>
+
+ <ol type="a">
+ <li>The attached device supports Android accessory mode and is already in accessory mode.</li>
+
+ <li>The attached device supports Android accessory mode, but it is not in accessory mode.</li>
+
+ <li>The attached device does not support Android accessory mode.</li>
+ </ol>
+
+ <p>During the initial connection, the accessory should check the vendor and product IDs of the
+ connected device's USB device descriptor. The vendor ID should match Google's ID (0x18D1) and the
+ product ID should be 0x2D00 or 0x2D01 if the device is already in accessory mode (case A). If so,
+ the accessory can now <a href="#establish">establish communication with the device</a> through
+ bulk transfer endpoints with its own communication protocol. There is no need to start the device
+ in accessory mode.</p>
+
+ <p class="note"><strong>Note:</strong> 0x2D00 is reserved for Android-powered devices that
+ support accessory mode. 0x2D01 is reserved for devices that support accessory mode as well as the
+ ADB (Android Debug Bridge) protocol, which exposes a second interface with two bulk endpoints for
+ ADB. You can use these endpoints for debugging the accessory application if you are simulating
+ the accessory on a computer. In general, do not use this interface unless your accessory is
+ implementing a passthrough to ADB on the device.</p>
+
+ <p>If the vendor and product ID do not match, there is no way to distinguish between states b and
+ c, so the accessory <a href="#start">attempts to start the device in accessory mode</a> to figure
+ out if the device is supported.</p>
+
+ <h3 id="start">Attempt to start the device in accessory mode</h3>
+
+ <p>If the vendor and product IDs do not correspond to an Android-powered device in accessory
+ mode, the accessory cannot discern whether the device supports accessory mode and is not in that
+ state, or if the device does not support accessory mode at all. This is because devices that
+ support accessory mode but aren't in it initially report the device's manufacturer vendor ID and
+ product ID, and not the special Google ones. In either case, the accessory should try to start
+ the device into accessory mode to figure out if the device supports it. The following steps
+ explain how to do this:</p>
+
+ <ol>
+ <li>Send a 51 control request ("Get Protocol") to figure out if the device supports the Android
+ accessory protocol. A non-zero number is returned if the protocol is supported, which
+ represents the version of the protocol that the device supports (currently, only version 1
+ exists). This request is a control request on endpoint 0 with the following characteristics:
+ <pre>
+requestType: USB_DIR_IN | USB_TYPE_VENDOR
+request: 51
+value: 0
+index: 0
+data: protocol version number (16 bits little endian sent from the device to the accessory)
+</pre>
+ </li>
+
+ <li>If the device returns a proper protocol version, send identifying string information to the
+ device. This information allows the device to figure out an appropriate application for this
+ accessory and also present the user with a URL if an appropriate application does not exist.
+ These requests are control requests on endpoint 0 (for each string ID) with the following
+ characteristics:
+ <pre>
+requestType: USB_DIR_OUT | USB_TYPE_VENDOR
+request: 52
+value: 0
+index: string ID
+data zero terminated UTF8 string sent from accessory to device
+</pre>
+
+ <p>The following string IDs are supported, with a maximum size of 256 bytes for each string
+ (must be zero terminated with \0).</p>
+ <pre>
+manufacturer name: 1
+model name: 2
+description: 3
+version: 4
+URI: 5
+serial number: 6
+</pre>
+ </li>
+
+ <li>When the identifying strings are sent, request the device start up in accessory mode. This
+ request is a control request on endpoint 0 with the following characteristics:
+ <pre>
+requestType: USB_DIR_OUT | USB_TYPE_VENDOR
+request: 53
+value: 0
+index: 0
+data: none
+</pre>
+ </li>
+ </ol>
+
+ <p>After sending the final control request, the connected USB device should re-introduce itself
+ on the bus in accessory mode and the accessory can re-enumerate the connected devices. The
+ algorithm jumps back to <a href="#determine">determining the device's accessory mode support</a>
+ to check for the vendor and product ID. The vendor ID and product ID of the device will be
+ different if the device successfully switched to accessory mode and will now correspond to
+ Google's vendor and product IDs instead of the device manufacturer's IDs. The accessory can now
+ <a href="#establish">establish communication with the device</a>.</p>
+
+ <p>If at any point these steps fail, the device does not support Android accessory mode and the
+ accessory should wait for the next device to be connected.</p>
+
+ <h3 id="establish">Establish communication with the device</h3>
+
+ <p>If an Android-powered device in accessory mode is detected, the accessory can query the
+ device's interface and endpoint descriptors to obtain the bulk endpoints to communicate with the
+ device. An Android-powered device that has a product ID of 0x2D00 has one interface with two bulk
+ endpoints for input and output communication. A device with product ID of 0x2D01 has two
+ interfaces with two bulk endpoints each for input and output communication. The first interface
+ is for standard communication while the second interface is for ADB communication. To communicate
+ on an interface, all you need to do is find the first bulk input and output endpoints, set the
+ device's configuration to a value of 1 with a SET_CONFIGURATION (0x09) device request, then
+ communicate using the endpoints.</p>
+
+ <h2 id="firmware">How the ADK board communicates with an Android-powered Device in Accessory
+ Mode</h2>
+
+ <p>If you have access to the ADK board and shield, the following sections describe the firmware
+ code that you installed onto the ADK board. The firmware demonstrates a practical example of how
+ to communicate with an Android-powered device. Even if you do not have the ADK board and shield,
+ reading through how the hardware detects and interacts with devices in accessory mode is still
+ useful if you want to port the code over for your own accessories.</p>
+
+ <p>The important pieces of the firmware are the
+ <code>accessory/demokit/demokit/demokit.pde</code> sketch, which is the code that receives and
+ sends data to the DemoKit application running on the Android-powered device. The code to detect
+ and set up communication with the Android-powered device is contained in the
+ <code>accessory/arduino_libs/AndroidAccessory/AndroidAccessory.h</code> and
+ <code>accessory/arduino_libs/AndroidAccessory/AndroidAccessory.cpp</code> files. This code
+ includes most of the logic that will help you implement your own accessory's firmware. It might
+ be useful to have all three of these files open in a text editor as you read through these next
+ sections.</p>
+
+ <p>The following sections describe the firmware code in the context of the algorithm described in
+ <a href="#how">How an Accessory Communicates with an Android-powered Device in Accessory
+ Mode</a>.</p>
+
+ <h3 id="wait-adk">Wait for and detect connected devices</h3>
+
+ <p>In the firmware code (<code>demokit.pde</code>), the <code>loop()</code> function runs
+ repeatedly and calls <code>AndroidAccessory::isConnected()</code> to check for any connected
+ devices. If there is a connected device, it continuously updates the input and output streams
+ going to and from the board and application. If nothing is connected, it continuously checks for
+ a device to be connected:</p>
+ <pre>
+...
+
+AndroidAccessory acc("Google, Inc.",
+ "DemoKit",
+ "DemoKit Arduino Board",
+ "1.0",
+ "http://www.android.com",
+ "0000000012345678");
+
+...
+void loop()
+{
+...
+ if (acc.isConnected()) {
+ //communicate with Android application
+ }
+ else{
+ //set the accessory to its default state
+ }
+...
+}
+</pre>
+
+ <h3 id="determine-adk">Determine the connected device's accessory mode support</h3>
+
+ <p>When a device is connected to the ADK board, it can already be in accessory mode, support
+ accessory mode and is not in that mode, or does not support accessory mode. The
+ <code>AndroidAccessory::isConnected()</code> method checks for these cases and responds
+ accordingly when the <code>loop()</code> function calls it. This function first checks to see if
+ the device that is connected hasn't already been handled. If not, it gets the connected device's
+ device descriptor to figure out if the device is already in accessory mode by calling
+ <code>AndroidAccessory::isAccessoryDevice()</code>. This method checks the vendor and product ID
+ of the device descriptor. A device in accessory mode has a vendor ID of 0x18D1 and a product ID
+ of 0x2D00 or 0x2D01. If the device is in accessory mode, then the ADK board can <a href=
+ "#establish-a">establish communication with the device</a>. If not, the board <a href=
+ "start-a">attempts to start the device in accessory mode</a>.</p>
+ <pre>
+bool AndroidAccessory::isConnected(void)
+{
+ USB_DEVICE_DESCRIPTOR *devDesc = (USB_DEVICE_DESCRIPTOR *) descBuff;
+ byte err;
+
+ max.Task();
+ usb.Task();
+
+ if (!connected &&
+ usb.getUsbTaskState() >= USB_STATE_CONFIGURING &&
+ usb.getUsbTaskState() != USB_STATE_RUNNING) {
+ Serial.print("\nDevice addressed... ");
+ Serial.print("Requesting device descriptor.");
+
+ err = usb.getDevDescr(1, 0, 0x12, (char *) devDesc);
+ if (err) {
+ Serial.print("\nDevice descriptor cannot be retrieved. Program Halted\n");
+ while(1);
+ }
+
+ if (isAccessoryDevice(devDesc)) {
+ Serial.print("found android accessory device\n");
+
+ connected = configureAndroid();
+ } else {
+ Serial.print("found possible device. switching to serial mode\n");
+ switchDevice(1);
+ }
+ } else if (usb.getUsbTaskState() == USB_DETACHED_SUBSTATE_WAIT_FOR_DEVICE) {
+ connected = false;
+ }
+
+ return connected;
+}
+</pre>
+
+ <h3 id="start-adk">Attempt to start the device in accessory mode</h3>
+
+ <p>If the device is not already in accessory mode, then the ADK board must determine whether or
+ not it supports it by sending control request 51 to check the version of the USB accessory
+ protocol that the device supports (see <code>AndroidAccessory::getProtocol()</code>). Protocol
+ version 1 is the only version for now, but this can be an integer greater than zero in the
+ future. If the appropriate protocol version is returned, the board sends control request 52 (one
+ for each string with <code>AndroidAcessory:sendString()</code>) to send it's identifying
+ information, and tries to start the device in accessory mode with control request 53. The
+ <code>AndroidAccessory::switchDevice()</code> method takes care of this:</p>
+ <pre>
+bool AndroidAccessory::switchDevice(byte addr)
+{
+ int protocol = getProtocol(addr);
+ if (protocol == 1) {
+ Serial.print("device supports protocol 1\n");
+ } else {
+ Serial.print("could not read device protocol version\n");
+ return false;
+ }
+
+ sendString(addr, ACCESSORY_STRING_MANUFACTURER, manufacturer);
+ sendString(addr, ACCESSORY_STRING_MODEL, model);
+ sendString(addr, ACCESSORY_STRING_DESCRIPTION, description);
+ sendString(addr, ACCESSORY_STRING_VERSION, version);
+ sendString(addr, ACCESSORY_STRING_URI, uri);
+ sendString(addr, ACCESSORY_STRING_SERIAL, serial);
+
+ usb.ctrlReq(addr, 0, USB_SETUP_HOST_TO_DEVICE | USB_SETUP_TYPE_VENDOR | USB_SETUP_RECIPIENT_DEVICE,
+ ACCESSORY_START, 0, 0, 0, 0, NULL);
+ return true;
+}
+</pre>If this method returns false, the board waits until a new device is connected. If it is
+successful, the device displays itself on the USB bus as being in accessory mode when the ADK board
+re-enumerates the bus. When the device is in accessory mode, the accessory then <a href=
+"establish-a">establishes communication with the device</a>.
+
+ <h3 id="establish-adk">Establish communication with the device</h3>
+
+ <p>If a device is detected as being in accessory mode, the accessory must find the proper bulk
+ endpoints and set up communication with the device. When the ADK board detects an Android-powered
+ device in accessory mode, it calls the <code>AndroidAccessory::configureAndroid()</code>
+ function:</p>
+ <pre>
+...
+if (isAccessoryDevice(devDesc)) {
+ Serial.print("found android acessory device\n");
+
+ connected = configureAndroid();
+ }
+...
+</pre>
+
+ <p>which in turn calls the <code>findEndpoints()</code> function:</p>
+ <pre>
+...
+bool AndroidAccessory::configureAndroid(void)
+{
+ byte err;
+ EP_RECORD inEp, outEp;
+
+ if (!findEndpoints(1, &inEp, &outEp))
+ return false;
+...
+</pre>
+
+ <p>The <code>AndroidAccessory::findEndpoints()</code> function queries the Android-powered
+ device's configuration descriptor and finds the bulk data endpoints in which to communicate with
+ the USB device. To do this, it first gets the device's first four bytes of the configuration
+ descriptor (only need descBuff[2] and descBuff[3]), which contains the information about the
+ total length of data returned by getting the descriptor. This data is used to determine whether
+ or not the descriptor can fit in the descriptor buffer. This descriptor also contains information
+ about all the interfaces and endpoint descriptors. If the descriptor is of appropriate size, the
+ method reads the entire configuration descriptor and fills the entire descriptor buffer with this
+ device's configuration descriptor. If for some reason the descriptor is no longer attainable, an
+ error is returned.</p>
+ <pre>
+...
+
+bool AndroidAccessory::findEndpoints(byte addr, EP_RECORD *inEp, EP_RECORD *outEp)
+{
+ int len;
+ byte err;
+ uint8_t *p;
+
+ err = usb.getConfDescr(addr, 0, 4, 0, (char *)descBuff);
+ if (err) {
+ Serial.print("Can't get config descriptor length\n");
+ return false;
+ }
+
+
+ len = descBuff[2] | ((int)descBuff[3] << 8);
+ if (len > sizeof(descBuff)) {
+ Serial.print("config descriptor too large\n");
+ /* might want to truncate here */
+ return false;
+ }
+
+ err = usb.getConfDescr(addr, 0, len, 0, (char *)descBuff);
+ if (err) {
+ Serial.print("Can't get config descriptor\n");
+ return false;
+ }
+
+...
+</pre>
+
+ <p>Once the descriptor is in memory, a pointer is assigned to the first position of the buffer
+ and is used to index the buffer for reading. There are two endpoint pointers (input and output)
+ that are passed into <code>AndroidAccessory::findEndpoints()</code> and their addresses are set
+ to 0, because the code hasn't found any suitable bulk endpoints yet. A loop reads the buffer,
+ parsing each configuration, interface, or endpoint descriptor. For each descriptor, Position 0
+ always contains the size of the descriptor in bytes and position 1 always contains the descriptor
+ type. Using these two values, the loop skips any configuration and interface descriptors and
+ increments the buffer with the <code>descLen</code> variable to get to the next descriptor.</p>
+
+ <p class="note"><strong>Note:</strong> An Android-powered device in accessory mode can
+ potentially have two interfaces, one for the default communication to the device and the other
+ for ADB communication. The default communication interface is always indexed first, so finding
+ the first input and output bulk endpoints will return the default communication endpoints, which
+ is what the <code>demokit.pde</code> sketch does. If you are writing your own firmware, the logic
+ to find the appropriate endpoints for your accessory might be different.</p>
+
+ <p>When it finds the first input and output endpoint descriptors, it sets the endpoint pointers
+ to those addresses. If the findEndpoints() function finds both an input and output endpoint, it
+ returns true. It ignores any other endpoints that it finds (the endpoints for the ADB interface,
+ if present).</p>
+ <pre>
+...
+ p = descBuff;
+ inEp->epAddr = 0;
+ outEp->epAddr = 0;
+ while (p < (descBuff + len)){
+ uint8_t descLen = p[0];
+ uint8_t descType = p[1];
+ USB_ENDPOINT_DESCRIPTOR *epDesc;
+ EP_RECORD *ep;
+
+ switch (descType) {
+ case USB_DESCRIPTOR_CONFIGURATION:
+ Serial.print("config desc\n");
+ break;
+
+ case USB_DESCRIPTOR_INTERFACE:
+ Serial.print("interface desc\n");
+ break;
+
+ case USB_DESCRIPTOR_ENDPOINT:
+ epDesc = (USB_ENDPOINT_DESCRIPTOR *)p;
+ if (!inEp->epAddr && (epDesc->bEndpointAddress & 0x80))
+ ep = inEp;
+ else if (!outEp->epAddr)
+ ep = outEp;
+ else
+ ep = NULL;
+
+ if (ep) {
+ ep->epAddr = epDesc->bEndpointAddress & 0x7f;
+ ep->Attr = epDesc->bmAttributes;
+ ep->MaxPktSize = epDesc->wMaxPacketSize;
+ ep->sndToggle = bmSNDTOG0;
+ ep->rcvToggle = bmRCVTOG0;
+ }
+ break;
+
+ default:
+ Serial.print("unkown desc type ");
+ Serial.println( descType, HEX);
+ break;
+ }
+
+ p += descLen;
+ }
+
+ if (!(inEp->epAddr && outEp->epAddr))
+ Serial.println("can't find accessory endpoints");
+
+ return inEp->epAddr && outEp->epAddr;
+}
+
+...
+</pre>
+
+ <p>Back in the <code>configureAndroid()</code> function, if there were endpoints found, they are
+ appropriately set up for communication. The device's configuration is set to 1 and the state of
+ the device is set to "running", which signifies that the device is properly set up to communicate
+ with your USB accessory. Setting this status prevents the device from being re-detected and
+ re-configured in the <code>AndroidAccessory::isConnected()</code> function.</p>
+ <pre>
+bool AndroidAccessory::configureAndroid(void)
+{
+ byte err;
+ EP_RECORD inEp, outEp;
+
+ if (!findEndpoints(1, &inEp, &outEp))
+ return false;
+
+ memset(&epRecord, 0x0, sizeof(epRecord));
+
+ epRecord[inEp.epAddr] = inEp;
+ if (outEp.epAddr != inEp.epAddr)
+ epRecord[outEp.epAddr] = outEp;
+
+ in = inEp.epAddr;
+ out = outEp.epAddr;
+
+ Serial.print("inEp: ");
+ Serial.println(inEp.epAddr, HEX);
+ Serial.print("outEp: ");
+ Serial.println(outEp.epAddr, HEX);
+
+ epRecord[0] = *(usb.getDevTableEntry(0,0));
+ usb.setDevTableEntry(1, epRecord);
+
+ err = usb.setConf( 1, 0, 1 );
+ if (err) {
+ Serial.print("Can't set config to 1\n");
+ return false;
+ }
+
+ usb.setUsbTaskState( USB_STATE_RUNNING );
+
+ return true;
+}
+</pre>
+
+ <p>Lastly, methods to read and write to the appropriate endpoints are needed. The
+ <code>demokit.pde</code> sketch calls these methods depending on the data that is read from the
+ Android-powered device or sent by the ADK board. For instance, moving the joystick on the ADK
+ shield writes data that is read by the DemoKit application running on the Android-powered device.
+ Moving sliders on the DemoKit application is read by the <code>demokit.pde</code> sketch and
+ changes the state of the accessory, such as lighting up or changing the color of the LED
+ lights.</p>
+ <pre>
+int AndroidAccessory::read(void *buff, int len, unsigned int nakLimit) {
+ return usb.newInTransfer(1, in, len, (char *)buff, nakLimit); }
+
+int AndroidAccessory::write(void *buff, int len) {
+ usb.outTransfer(1, out, len, (char *)buff);
+ return len; }
+
+</pre>
+
+ <p>See the <code>firmware/demokit/demokit.pde</code> file for information about how the ADK board
+ reads and writes data.</p>
\ No newline at end of file
diff --git a/docs/html/images/screens_support/avd-start.png b/docs/html/images/screens_support/avd-start.png
new file mode 100644
index 0000000..affb4bd
--- /dev/null
+++ b/docs/html/images/screens_support/avd-start.png
Binary files differ
diff --git a/docs/html/images/screens_support/avds-config.png b/docs/html/images/screens_support/avds-config.png
index 7db8c73..3af1c39 100644
--- a/docs/html/images/screens_support/avds-config.png
+++ b/docs/html/images/screens_support/avds-config.png
Binary files differ
diff --git a/docs/html/images/screens_support/compat-mode-on.png b/docs/html/images/screens_support/compat-mode-on.png
new file mode 100644
index 0000000..ebdbf41
--- /dev/null
+++ b/docs/html/images/screens_support/compat-mode-on.png
Binary files differ
diff --git a/docs/html/images/screens_support/density-test-bad.png b/docs/html/images/screens_support/density-test-bad.png
new file mode 100644
index 0000000..d3fe1c3
--- /dev/null
+++ b/docs/html/images/screens_support/density-test-bad.png
Binary files differ
diff --git a/docs/html/images/screens_support/density-test-good.png b/docs/html/images/screens_support/density-test-good.png
new file mode 100644
index 0000000..f2eb47c
--- /dev/null
+++ b/docs/html/images/screens_support/density-test-good.png
Binary files differ
diff --git a/docs/html/images/screens_support/icon-density-example.png b/docs/html/images/screens_support/icon-density-example.png
new file mode 100644
index 0000000..3cac5ee
--- /dev/null
+++ b/docs/html/images/screens_support/icon-density-example.png
Binary files differ
diff --git a/docs/html/images/screens_support/scale-test.png b/docs/html/images/screens_support/scale-test.png
index f4fc662..19cf34f 100644
--- a/docs/html/images/screens_support/scale-test.png
+++ b/docs/html/images/screens_support/scale-test.png
Binary files differ
diff --git a/docs/html/images/screens_support/screens-densities.png b/docs/html/images/screens_support/screens-densities.png
new file mode 100644
index 0000000..edbd1e3
--- /dev/null
+++ b/docs/html/images/screens_support/screens-densities.png
Binary files differ
diff --git a/docs/html/images/screens_support/screens-ranges.png b/docs/html/images/screens_support/screens-ranges.png
index dce6264..d8a0ffa 100644
--- a/docs/html/images/screens_support/screens-ranges.png
+++ b/docs/html/images/screens_support/screens-ranges.png
Binary files differ
diff --git a/docs/html/resources/dashboard/opengl.jd b/docs/html/resources/dashboard/opengl.jd
new file mode 100644
index 0000000..dac8ce5
--- /dev/null
+++ b/docs/html/resources/dashboard/opengl.jd
@@ -0,0 +1,79 @@
+page.title=OpenGL ES Versions
+@jd:body
+
+<style type="text/css">
+
+div.dashboard-panel {
+ max-width:1000px;
+ margin:0 0 2em 0;
+ padding:20px 20px 0 20px;
+ border:1px solid #d3ecf5;
+ border-radius:7px;
+ -moz-border-radius:7px;
+ -webkit-border-radius:7px;
+ background-color: #DAF3FC;
+ box-shadow:2px 3px 1px #eee;
+ -moz-box-shadow:2px 3px 1px #eee;
+ -webkit-box-shadow:2px 3px 1px #eee;
+ overflow:hidden;
+}
+#jd-content div.dashboard-panel img {
+ margin:0 20px 20px 0;
+ padding:0;
+ border:1px solid #ccc;
+ float:left;
+}
+#jd-content div.dashboard-panel table {
+ margin:0 0 20px 0;
+ float:left;
+ background-color:#fff;
+}
+div.dashboard-panel p {
+ clear:left;
+}
+div.dashboard-panel th {
+ white-space:nowrap;
+}
+</style>
+
+<p>This page provides data about the relative number of active devices that support a particular
+version of OpenGL ES. Note that support for one particular version of OpenGL ES also implies
+support for any lower version (for example, support for version 2.0 also implies support for
+1.1).</p>
+
+<p>To declare which version of OpenGL ES your application requires, you should use the {@code
+android:glEsVersion} attribute of the <a
+href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a>
+element. You can also use the <a
+href="{@docRoot}guide/topics/manifest/supports-gl-texture-element.html">{@code
+<supports-gl-texture>}</a> element to declare the GL compression formats that your application
+uses.</p>
+
+<p class="note"><strong>Note:</strong> This data is based on the number
+of Android devices that have accessed Android Market within a 7-day period
+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%20ES%201.1|GL%20ES%202.0&chd=t%3A8.9,91.1" />
+
+<table>
+<tr>
+<th scope="col">OpenGL ES Version</th>
+<th scope="col">Distribution</th>
+</tr>
+<tr>
+<td>1.1</th>
+<td>8.9%</td>
+</tr>
+<tr>
+<td>2.0</th>
+<td>91.1%</td>
+</tr>
+</table>
+
+<p><em>Data collected during a 7-day period ending on May 6, 2011</em></p>
+</div>
+
diff --git a/docs/html/resources/dashboard/screens.jd b/docs/html/resources/dashboard/screens.jd
index 90f3f1a..bdaae0d 100644
--- a/docs/html/resources/dashboard/screens.jd
+++ b/docs/html/resources/dashboard/screens.jd
@@ -36,46 +36,66 @@
}
</style>
-<p>This page provides data about the relative number of active devices
-using a particular type of screen, including the screen size and density. For information about how
-your application can support multiple screen types, see <a
-href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a>.</p>
+<p> This page provides data about the relative number of active devices that have a particular
+screen configuration, defined by a combination of screen size and density. To simplify the way that
+you design your user interfaces for different screen configurations, Android divides the range of
+actual screen sizes and densities into:</p>
+
+<ul>
+<li>A set of four generalized <strong>sizes</strong>: <em>small</em>, <em>normal</em>,
+<em>large</em>, and <em>xlarge</em></em></li>
+<li>A set of four generalized <strong>densities</strong>: <em>ldpi</em> (low), <em>mdpi</em>
+(medium), <em>hdpi</em> (high), and <em>xhdpi</em> (extra high)</li>
+</ul>
+
+<p>For information about how you can support multiple screen configurations in your
+application, see <a href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
+Screens</a>.</p>
<p class="note"><strong>Note:</strong> This data is based on the number
-of Android devices that have accessed Android Market within a 14-day period
+of Android devices that have accessed Android Market within a 7-day period
ending on the data collection date noted below.</p>
<div class="dashboard-panel">
-<img alt="" width="460" height="250"
-src="http://chart.apis.google.com/chart?&cht=p&chs=460x250&chd=t:2.3,0.4,45.9,51.2&chl=Small%20/%
-20ldpi|Normal%20/%20ldpi|Normal%20/%20mdpi|Normal%20/%20hdpi&chco=c4df9b,6fad0c" />
+<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/%20mdpi|normal%20/%20hdpi|normal%20/%20ldpi|normal%20/%20mdpi|small%20/%20hdpi&chd=t%3A0.5,2.6,75.5,1.2,17.1,3.2" />
<table>
<tr>
<th></th>
-<th scope="col">Low Density</th>
-<th scope="col">Medium Density</th>
-<th scope="col">High Density</th>
+<th scope="col">ldpi</th>
+<th scope="col">mdpi</th>
+<th scope="col">hdpi</th>
+<th scope="col">xhdpi</th>
</tr>
-<tr><th scope="row">Small</th>
-<td class='cent hi'>2.3%</td>
-<td></td>
-<td></td>
+<tr><th scope="row">small</th>
+<td></td> <!-- ldpi -->
+<td></td> <!-- mdpi -->
+<td>3.2%</td> <!-- hdpi -->
+<td></td> <!-- xhdpi -->
</tr>
-<tr><th scope="row">Normal</th>
-<td class='cent '>0.4%</td>
-<td class='cent hi'>45.9%</td>
-<td class='cent hi'>51.2%</td>
+<tr><th scope="row">normal</th>
+<td>1.2%</td> <!-- ldpi -->
+<td>17.1%</td> <!-- mdpi -->
+<td>75.5%</td> <!-- hdpi -->
+<td></td> <!-- xhdpi -->
</tr>
-<tr><th scope="row">Large</th>
-<td></td>
-<td></td>
-<td></td>
+<tr><th scope="row">large</th>
+<td></td> <!-- ldpi -->
+<td>2.6%</td> <!-- mdpi -->
+<td></td> <!-- hdpi -->
+<td></td> <!-- xhdpi -->
+</tr>
+<tr><th scope="row">xlarge</th>
+<td></td> <!-- ldpi -->
+<td>0.5%</td> <!-- mdpi -->
+<td></td> <!-- hdpi -->
+<td></td> <!-- xhdpi -->
</tr>
</table>
-<p><em>Data collected during two weeks ending on August 2, 2010</em></p>
+<p><em>Data collected during a 7-day period ending on May 6, 2011</em></p>
</div>
diff --git a/docs/html/resources/resources_toc.cs b/docs/html/resources/resources_toc.cs
index a2580a6..c7dd916 100644
--- a/docs/html/resources/resources_toc.cs
+++ b/docs/html/resources/resources_toc.cs
@@ -81,6 +81,9 @@
<li><a href="<?cs var:toroot ?>resources/dashboard/screens.html">
<span class="en">Screen Sizes & Densities</span>
</a></li>
+ <li><a href="<?cs var:toroot ?>resources/dashboard/opengl.html">
+ <span class="en">OpenGL ES Versions</span>
+ </a></li>
</ul>
</li><?cs
/if
diff --git a/docs/html/sdk/android-2.3.4.jd b/docs/html/sdk/android-2.3.4.jd
new file mode 100644
index 0000000..e5765d3
--- /dev/null
+++ b/docs/html/sdk/android-2.3.4.jd
@@ -0,0 +1,379 @@
+page.title=Android 2.3.4 Platform
+sdk.platform.version=2.3.4
+sdk.platform.apiLevel=10
+
+
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>In this document</h2>
+<ol>
+ <li><a href="#relnotes">Revisions</a></li>
+ <li><a href="#api">API Overview</a></li>
+ <li><a href="#openaccessory">Open Accessory Library</a></li>
+ <li><a href="#api-level">API Level</a></li>
+ <li><a href="#apps">Built-in Applications</a></li>
+ <li><a href="#locs">Locales</a></li>
+ <li><a href="#skins">Emulator Skins</a></li>
+</ol>
+
+<h2>Reference</h2>
+<ol>
+<li><a
+href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API
+Differences Report »</a> </li>
+</ol>
+
+<h2>See Also</h2>
+<ol>
+ <li><a href="{@docRoot}sdk/adding-components.html">Adding SDK Components</a></li>
+</ol>
+
+</div>
+</div>
+
+<p>
+<em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p>
+
+<p>Android 2.3.4 is a maintenance release that adds several bug fixes and patches
+to the Android 2.3 platform, without any API changes from Android 2.3.3. Additionally,
+Android 2.3.4 brings support for the Open Accessory API to mobile devices,
+through the optional <a href="#usb">Open Accessory Library</a>. </p>
+
+<p>For developers, the Android {@sdkPlatformVersion} platform and the Open
+Accessory Library are available together in the latest version of the Google
+APIs Add-On, a downloadable component for the Android SDK.</p>
+
+<p>To get started developing or testing against Android {@sdkPlatformVersion},
+use the Android SDK Manager to download the latest version of the Google APIs
+Add-On 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/index.html">download the SDK Starter
+Package</a> first.</p>
+
+<p>For a high-level introduction to Android 2.3, see the <a
+href="{@docRoot}sdk/android-2.3-highlights.html">Platform Highlights</a>.</p>
+
+
+<h2 id="relnotes">Revisions</h2>
+
+<p>The sections below provide notes about successive releases of
+the Android {@sdkPlatformVersion} platform component for the Android SDK, as denoted by
+revision number. To determine what revision(s) of the Android
+{@sdkPlatformVersion} platforms are installed in your SDK environment, refer to
+the "Installed Packages" listing in the Android SDK and AVD Manager.</p>
+
+<script type="text/javascript">
+function toggleDiv(link) {
+ var toggleable = $(link).parent();
+ if (toggleable.hasClass("closed")) {
+ //$(".toggleme", toggleable).slideDown("fast");
+ toggleable.removeClass("closed");
+ toggleable.addClass("open");
+ $(".toggle-img", toggleable).attr("title", "hide").attr("src", (toRoot + "assets/images/triangle-opened.png"));
+ } else {
+ //$(".toggleme", toggleable).slideUp("fast");
+ toggleable.removeClass("open");
+ toggleable.addClass("closed");
+ $(".toggle-img", toggleable).attr("title", "show").attr("src", (toRoot + "assets/images/triangle-closed.png"));
+ }
+ return false;
+}
+</script>
+<style>
+.toggleable {
+ padding: .25em 1em 0em 1em;
+ margin-bottom: 0;
+}
+.toggleme {
+ padding: 1em 1em 0 2em;
+ line-height:1em;
+}
+.toggleable a {
+ text-decoration:none;
+}
+.toggleme a {
+ text-decoration:underline;
+}
+.toggleable.closed .toggleme {
+ display:none;
+}
+#jd-content .toggle-img {
+ margin:0;
+}
+</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" />
+ Android {@sdkPlatformVersion}, Revision 1</a> <em>(May 2011)</em></a>
+ <div class="toggleme">
+<dl>
+<dt>Dependencies:</dt>
+<dd>
+<p>Requires SDK Tools r11 or higher.</p>
+</dd>
+
+</dl>
+ </div>
+</div>
+
+
+<h2 id="api">API Overview</h2>
+
+<p>Android 2.3.4 provides the same framework API to applications as Android 2.3.3
+(API level 10). For a summary of the API, see the
+<a href="{@docRoot}sdk/android-2.3.3.html">Android 2.3.3 version notes</a>.</p>
+
+
+<h2 id="openaccessory">Open Accessory Library</h3>
+
+<p><em>Open Accessory</em> is a new capability for integrating
+connected peripherals with applications running on the platform. The capability
+is based on a USB (Universal Serial Bus) stack built into the platform and an
+API exposed to applications. Peripherals that attach to Android-powered devices
+as accessories connect as USB hosts. </p>
+
+<p>Open Accessory is introduced in <a
+href="{@docRoot}sdk/android-3.1.html#usb">Android 3.1</a> (API level 12), but is
+made available to devices running Android 2.3.4 by means of an optional external
+library, the Open Accessory Library. The library exposes a framework API that
+lets applications discover, communicate with, and manage a variety of device
+types connected over USB. It also provides the implementation of the API against
+parts of the Android platform that are not directly exposed to applications in
+Android 2.3.4.</p>
+
+<p>The Open Accessory Library is optional on any given device. Device
+manufacturers may choose whether to include the Open Accessory Library in their
+products or exclude it. The library is forward-compatible with Android 3.1, so
+applications developed against Android 2.3.4 will run properly on devices
+running Android 3.1, if those devices support USB accessories. </p>
+
+<p>The API provided by the Open Accessory Library is based on the Open Accessory
+API provided in Android 3.1. In most areas, you can use the same techniques and
+APIs. However, developing for the Open Accessory Library on Android 2.3.4 differs
+from the standard USB API in these ways:
+
+<ul>
+<li>Obtaining a {@link android.hardware.usb.UsbManager} object — To obtain
+a {@link android.hardware.usb.UsbManager} object when using the add-on library,
+use the helper method <code>getInstance()</code> rather than {@link
+android.content.Context#getSystemService(java.lang.String) getSystemService()}
+For example:
+
+<pre>UsbManager manager = UsbManager.getInstance(this);</pre></li>
+
+<li>Obtaining a {@link android.hardware.usb.UsbAccessory} from a filtered intent
+— When you filter for a connected device or accessory with an intent
+filter, the {@link android.hardware.usb.UsbAccessory} object is contained
+inside the intent that is passed to your application. If you are using the
+add-on library, you can get the {@link android.hardware.usb.UsbAccessory} object
+in the following manner:
+
+<pre>UsbAccessory accessory = UsbManager.getAccessory(intent)</pre></li>
+
+<li>No USB host support — Android 2.3.4 and the Open Accessory Library do
+not support USB host mode (for example, through {@link
+android.hardware.usb.UsbDevice}), although USB host mode is supported in Android
+3.1. An Android-powered device running Android 2.3.4 can not function as a USB
+host. The library enables the Android-powered device to function as
+a peripheral only, with the connected accessory functioning as USB host
+(through {@link android.hardware.usb.UsbAccessory}).</li>
+</ul>
+
+<p>To develop apps using the Open Accessory Library, you need:</p>
+
+<ul>
+<li>The latest version of the Android SDK tools</li>
+<li>The latest version of the Google APIs add-on, which includes the library
+itself (for linking)</li>
+<li>An actual hardware device running Android 2.3.4 (or Android 3.1) with USB
+accessories support, for runtime testing against connected devices</li>
+</ul>
+
+<p>For a full discussion of how to develop applications that interact with USB
+accessories, please see the related <a
+href="{@docRoot}guide/topics/usb/index.html">developer documentation</a>.</p>
+
+<p>Additionally, developers can request filtering on Android Market, such that
+their applications are not available to users whose devices do not provide the
+appropriate accessory support. To request filtering, add the element below
+to the application manifest:</p>
+
+<pre><uses-feature
+ android:name="android.hardware.usb.accessory"
+ android:required="true"></pre>
+
+
+<h2 id="api-level">API Level</h2>
+
+<p>The Android 2.3.4 platform does <em>not</em> increment the API level —
+it uses the same API level as Android 2.3.3, API level 10.
+
+<p>To use APIs introduced in API level 10 in your application,
+you need compile the application against the Android library that is provided in
+the latest version of the Google APIs Add-On, which also includes the Open
+Accessory Library.</p>
+
+<p>Depending on your needs, you might
+also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code>
+attribute to the <code><uses-sdk></code> element in the application's
+manifest. If your application is designed to run only on Android 2.3.3 and higher,
+declaring the attribute prevents the application from being installed on earlier
+versions of the platform.</p>
+
+<p>For more information about how to use API Level, see the <a
+href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document. </p>
+
+<h2 id="apps">Built-in Applications</h2>
+
+<p>The system image included in the downloadable platform provides these
+built-in applications:</p>
+
+<table style="border:0;padding-bottom:0;margin-bottom:0;">
+<tr>
+<td style="border:0;padding-bottom:0;margin-bottom:0;">
+<ul>
+<li>Browser</li>
+<li>Calculator</li>
+<li>Camera</li>
+<li>Clock</li>
+<li>Contacts</li>
+<li>Cusom Locale</li>
+<li>Dev Tools</li>
+<li>Downloads</li>
+<li>Email</li>
+</ul>
+</td>
+<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
+<ul>
+<li>Gallery</li>
+<li>IMEs for Japanese, Chinese, and Latin text input</li>
+<li>Messaging</li>
+<li>Music</li>
+<li>Phone</li>
+<li>Search</li>
+<li>Settings</li>
+<li>Spare Parts (developer app)</li>
+<li>Speech Recorder</li>
+</ul>
+</td>
+</tr>
+</table>
+
+
+<h2 id="locs" style="margin-top:.75em;">Locales</h2>
+
+<p>The system image included in the downloadable SDK platform provides a variety of
+built-in locales. In some cases, region-specific strings are available for the
+locales. In other cases, a default version of the language is used. The
+languages that are available in the Android {@sdkPlatformVersion} system
+image are listed below (with <em>language</em>_<em>country/region</em> locale
+descriptor).</p>
+
+<table style="border:0;padding-bottom:0;margin-bottom:0;">
+<tr>
+<td style="border:0;padding-bottom:0;margin-bottom:0;">
+<ul>
+<li>Arabic, Egypt (ar_EG)</li>
+<li>Arabic, Israel (ar_IL)</li>
+<li>Bulgarian, Bulgaria (bg_BG)</li>
+<li>Catalan, Spain (ca_ES)</li>
+<li>Czech, Czech Republic (cs_CZ)</li>
+<li>Danish, Denmark(da_DK)</li>
+<li>German, Austria (de_AT)</li>
+<li>German, Switzerland (de_CH)</li>
+<li>German, Germany (de_DE)</li>
+<li>German, Liechtenstein (de_LI)</li>
+<li>Greek, Greece (el_GR)</li>
+<li>English, Australia (en_AU)</li>
+<li>English, Canada (en_CA)</li>
+<li>English, Britain (en_GB)</li>
+<li>English, Ireland (en_IE)</li>
+<li>English, India (en_IN)</li>
+<li>English, New Zealand (en_NZ)</li>
+<li>English, Singapore(en_SG)</li>
+<li>English, US (en_US)</li>
+<li>English, Zimbabwe (en_ZA)</li>
+<li>Spanish (es_ES)</li>
+<li>Spanish, US (es_US)</li>
+<li>Finnish, Finland (fi_FI)</li>
+<li>French, Belgium (fr_BE)</li>
+<li>French, Canada (fr_CA)</li>
+<li>French, Switzerland (fr_CH)</li>
+<li>French, France (fr_FR)</li>
+<li>Hebrew, Israel (he_IL)</li>
+<li>Hindi, India (hi_IN)</li>
+</ul>
+</td>
+<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
+<li>Croatian, Croatia (hr_HR)</li>
+<li>Hungarian, Hungary (hu_HU)</li>
+<li>Indonesian, Indonesia (id_ID)</li>
+<li>Italian, Switzerland (it_CH)</li>
+<li>Italian, Italy (it_IT)</li>
+<li>Japanese (ja_JP)</li>
+<li>Korean (ko_KR)</li>
+<li>Lithuanian, Lithuania (lt_LT)</li>
+<li>Latvian, Latvia (lv_LV)</li>
+<li>Norwegian-Bokmol, Norway(nb_NO)</li>
+<li>Dutch, Belgium (nl_BE)</li>
+<li>Dutch, Netherlands (nl_NL)</li>
+<li>Polish (pl_PL)</li>
+<li>Portuguese, Brazil (pt_BR)</li>
+<li>Portuguese, Portugal (pt_PT)</li>
+<li>Romanian, Romania (ro_RO)</li>
+<li>Russian (ru_RU)</li></li>
+<li>Slovak, Slovakia (sk_SK)</li>
+<li>Slovenian, Slovenia (sl_SI)</li>
+<li>Serbian (sr_RS)</li>
+<li>Swedish, Sweden (sv_SE)</li>
+<li>Thai, Thailand (th_TH)</li>
+<li>Tagalog, Philippines (tl_PH)</li>
+<li>Turkish, Turkey (tr_TR)</li>
+<li>Ukrainian, Ukraine (uk_UA)</li>
+<li>Vietnamese, Vietnam (vi_VN)</li>
+<li>Chinese, PRC (zh_CN)</li>
+<li>Chinese, Taiwan (zh_TW)</li>
+</td>
+</tr>
+</table>
+
+<p class="note"><strong>Note:</strong> The Android platform may support more
+locales than are included in the SDK system image. All of the supported locales
+are available in the <a href="http://source.android.com/">Android Open Source
+Project</a>.</p>
+
+<h2 id="skins">Emulator Skins</h2>
+
+<p>The downloadable platform includes a set of emulator skins that you can use
+for modeling your application in different screen sizes and resolutions. The
+emulator skins are:</p>
+
+<ul>
+ <li>
+ QVGA (240x320, low density, small screen)
+ </li>
+ <li>
+ WQVGA400 (240x400, low density, normal screen)
+ </li>
+ <li>
+ WQVGA432 (240x432, low density, normal screen)
+ </li>
+ <li>
+ HVGA (320x480, medium density, normal screen)
+ </li>
+ <li>
+ WVGA800 (480x800, high density, normal screen)
+ </li>
+ <li>
+ WVGA854 (480x854 high density, normal screen)
+ </li>
+</ul>
+
+<p>For more information about how to develop an application that displays
+and functions properly on all Android-powered devices, see <a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
+Screens</a>.</p>
diff --git a/docs/html/sdk/android-3.0-highlights.jd b/docs/html/sdk/android-3.0-highlights.jd
index d4fd002..33897de 100644
--- a/docs/html/sdk/android-3.0-highlights.jd
+++ b/docs/html/sdk/android-3.0-highlights.jd
@@ -39,10 +39,6 @@
</style>
-
-
-
-
<p>Welcome to Android 3.0!</p>
<p>The Android 3.0 platform introduces many new and exciting features for users and developers.
@@ -265,5 +261,3 @@
href="{@docRoot}sdk/android-3.0.html">Android 3.0 Platform</a> document.</p>
<p>For a video overview of platform features, see the Android 3.0 Sneak Peek. </p>
-
-
diff --git a/docs/html/sdk/android-3.0.jd b/docs/html/sdk/android-3.0.jd
index a81be20..d73bd63 100644
--- a/docs/html/sdk/android-3.0.jd
+++ b/docs/html/sdk/android-3.0.jd
@@ -559,7 +559,7 @@
<p>Provides a search box that you can configure to deliver search queries to a specified
activity and display search suggestions (in the same manner as the traditional search dialog). This
widget is particularly useful for offering a search widget in the Action Bar. For more information,
-see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface</p>.</li>
+see <a href="{@docRoot}guide/topics/search/search-dialog.html">Creating a Search Interface.</p></li>
<li>{@link android.widget.StackView}
<p>A view that displays its children in a 3D stack and allows users to swipe through
diff --git a/docs/html/sdk/android-3.1-highlights.jd b/docs/html/sdk/android-3.1-highlights.jd
new file mode 100644
index 0000000..3d132a3
--- /dev/null
+++ b/docs/html/sdk/android-3.1-highlights.jd
@@ -0,0 +1,380 @@
+page.title=Android 3.1 Platform Highlights
+
+@jd:body
+
+
+<style type="text/css">
+#jd-content {
+ max-width:1200px;
+}
+#jd-content div.screenshot {
+ float:left;
+ clear:left;
+ padding:15px 30px 15px 0;
+}
+#jd-content div.video {
+ float:right;
+ padding:0 60px 40px;
+ margin-top:-15px;
+}
+#jd-content table.columns {
+ margin:0 0 1em 0;
+}
+#jd-content table.columns td {
+ padding:0;
+}
+#jd-content table.columns td+td {
+ padding:0 2em;
+}
+#jd-content table.columns td img {
+ margin:0;
+}
+#jd-content table.columns td+td>*:first-child {
+ margin-top:-2em;
+}
+.green {
+ color:#8db529;
+ font-weight:bold;
+}
+</style>
+
+<p>Welcome to Android 3.1!</p>
+
+<p>Android 3.1 is an incremental platform release that refines many of the
+features introduced in Android 3.0. It builds on the same tablet-optimized UI
+and features offered in Android 3.0 and adds several new capabilities for
+users and developers. This document provides an overview of the new features and
+technologies introduced in Android 3.1. For a more detailed look at new
+developer APIs, see the <a href="{@docRoot}sdk/android-3.1.html">API
+Overview</a> document.</p>
+
+<p>For a high-level introduction to Android 3.0, please see the <a
+href="{@docRoot}sdk/android-3.0-highlights.html">Android 3.0 Platform
+Highlights</a>.</p>
+
+<ul>
+ <li><a href="#UserFeatures">New User Features</a></li>
+ <li><a href="#DeveloperApis">New Developer Features</a></li>
+</ul>
+
+<h2 id="UserFeatures" style="clear:right">New User Features</h2>
+
+<div style="padding-top:0em;">
+<div style="margin-right:1em;margin-left:1em;float:right;padding-top:2em;"><a href="images/3.1/home_full.png" target="_android"><img src="images/3.1/home.png" alt="" height="280" /></a>
+<div style="padding-left:1.25em;padding-bottom:1.25em;width:450px;font-size:.9em"><strong>Figure 1.</strong> An Android 3.1 Home screen.</div>
+</div>
+
+<h3>UI refinements</h3>
+
+<p>The Android 3.1 platform adds a variety of refinements to make the user
+interface more intuitive and more efficient to use.</p>
+
+<p>UI transitions are improved throughout the system and across the standard
+apps. The Launcher animation is optimized for faster, smoother transition to and
+from the Apps list. Adjustments in color, positioning, and text make UI elements
+easier to see, understand, and use. Accessibility is improved with consistent
+audible feedback throughout the UI and a new setting to let users customize the
+touch-hold interval to meet their needs.</p>
+
+<p>Navigation to and from the five home screens is now easier — touching
+the Home button in the system bar now takes you to the home screen most recently
+used. Settings offers an improved view of internal storage,
+showing the storage used by a larger set of file types. </p>
+
+<h3 id="accessories">Connectivity for USB accessories</h3>
+
+<p>Android 3.1 adds broad platform support for a variety of USB-connected
+peripherals and accessories. Users can attach many types of input devices
+(keyboards, mice, game controllers) and digital cameras. Applications can build
+on the platform’s USB support to extend connectivity to almost any type of USB
+device.</p>
+
+<p>The platform also adds new support for USB accessories — external
+hardware devices designed to attach to Android-powered devices as USB hosts. When an
+accessory is attached, the framework will look for a corresponding application
+and offer to launch it for the user. The accessory can also present a URL
+to the user, for downloading an appropriate application if one is not already
+installed. Users can interact with the application to control powered accessories such
+as robotics controllers; docking stations; diagnostic and musical equipment;
+kiosks; card readers; and much more.</p>
+
+<p>The platform’s USB capabilities rely on components in device hardware, so
+support for USB on specific devices may vary and is determined by device
+manufacturers.</p>
+
+<div style="padding-top:0em;">
+<div style="margin-right:.8em;float:left;width:200px;"><img src="{@docRoot}sdk/images/3.1/tasks.png" alt="" />
+<div style="padding-left:1em;padding-bottom:1em;xwidth:auto;font-size:.9em"><strong>Figure 2.</strong> The Recent Apps menu is now expandable and scrollable.</div>
+</div>
+
+<h3 id="recentapps">Expanded Recent Apps list</h3>
+
+<p>For improved multitasking and instant visual access to a much larger number
+of apps, the Recent Apps list is now expandable. Users can now scroll the list
+of recent apps vertically to see thumbnail images all of the tasks in progress
+and recently used apps, then touch a thumbnail to jump back into that task.</p>
+
+<h3 id="resizewidgets">Resizeable Home screen widgets</h3>
+
+<p>For more flexible Home screen customization, users can now resize their Home
+screen widgets using drag bars provided by the system. Users can expand widgets
+both horizontally and/or vertically to include more content, where supported by
+each widget.</p>
+
+
+<h3 id="keyboards">Support for external keyboards
+and pointing devices</h3>
+
+<p>Users can now attach almost any type of external keyboard or mouse to their
+Android-powered devices, to create a familiar environment and work more
+efficiently. One or more input devices can be attached to the system simultaneously
+over USB and/or Bluetooth HID, in any combination. No special configuration or
+driver is needed, in most cases. When multiple devices are connected, users can
+conveniently manage the active keyboard and IME using the keyboard settings that
+are available from the System bar.</p>
+
+<p>For pointing devices, the platform supports most types of mouse with a single
+button and optionally a scroll wheel, as well as similar devices such as
+trackballs. When these are connected, users can interact with the UI using
+point, select, drag, scroll, hover, and other standard actions.</p>
+
+<h3 id="joysticks">Support for joysticks and gamepads</h3>
+
+<p>To make the platform even better for gaming, Android 3.1 adds support for
+most PC joysticks and gamepads that are connected over USB or Bluetooth HID.</p>
+
+<p>For example, users can connect Sony Playstation™ 3 and XBox 360™ game
+controllers over USB (but not Bluetooth), Logitech Dual Action™ gamepads and
+flight sticks, or a car racing controller. Game controllers that use proprietary
+networking or pairing are not supported by default, but in general, the platform
+supports most PC-connectible joysticks and gamepads.</p>
+
+<h3 id="wifi">Robust Wi-Fi networking</h3>
+
+<p>Android 3.1 adds robust Wi-Fi features, to make sure that users and their
+apps can take full advantage of higher-speed Wi-Fi access at home, at work, and
+while away.</p>
+
+<p>A new high-performance Wi-Fi lock lets applications maintain
+high-performance Wi-Fi connections even when the device screen is off. Users can
+take advantage of this to play continuous streamed music, video, and voice
+services for long periods, even when the device is otherwise idle and the screen
+is off. </p>
+
+<p>Users can now configure an HTTP proxy for each individual Wi-Fi access
+point, by touch-hold of the access point in Settings. The browser uses the HTTP
+proxy when communicating with the network over the access point and other apps
+may also choose to do so. The platform also provides backup and restore of the
+user-defined IP and proxy settings.</p>
+<p>The platform adds support for Preferred Network Offload (PNO), a background
+scanning capability that conserves battery power savings in cases where Wi-Fi
+needs to be available continuously for long periods of time.</p>
+
+<h3 id="apps">Updated set of standard apps</h3>
+
+<p>The Android 3.1 platform includes an updated set of standard applications
+that are optimized for use on larger screen devices. The sections below
+highlight some of the new features.</p>
+
+<div style="padding-top:0em;">
+<div style="margin-right:1em;float:right;margin-left:1em;margin-top:1.5em;margin-bottom:0;padding-bottom:0;"><img src="{@docRoot}sdk/images/3.1/controls.png" alt="" height="280px" />
+<div style="padding-left:1.25em;padding-bottom:1.25em;margin-top:0;padding-top:0;font-size:.9em"><strong>Figure 3.</strong> Quick Controls menu in the Browser.</div>
+</div>
+</div>
+
+<p><strong>Browser</strong></p>
+
+<p>The Browser app includes a variety of new features and UI improvements that
+make viewing web content simpler, faster, and more convenient.</p>
+
+<p>The Quick Controls UI, accessible from Browser Settings, is extended and
+redesigned. Users can now use the controls to view thumbnails of open tabs and
+close the active tab, as well as access the overflow menu for instant access to
+Settings and other controls.</p>
+
+<p>To ensure a consistent viewing experience, the Browser extends it's support
+for popular web standards such as CSS 3D, animations, and CSS fixed
+positioning to all sites, mobile or desktop. It also adds support for embedded
+playback of HTML5 video content. To make it easier to manage favorite
+content, users can now save a web page locally for offline viewing, including
+all styling and images. For convenience when visiting Google sites, an improved
+auto-login UI lets users sign in quickly and manage access when multiple users
+are sharing a device.</p>
+
+<p>For best performance, the Browser adds support for plugins that use hardware
+accelerated rendering. Page zoom performance is also dramatically improved,
+making it faster to navigate and view web pages.</p>
+
+<p><strong>Gallery</strong></p>
+
+<p>The Gallery app now supports Picture Transfer Protocol (PTP), so that users
+can connect their cameras over USB and import their pictures to Gallery with a
+single touch. The app also copies the pictures to local storage and provides an
+indicator to let users see how much space is available.</p>
+
+<div style="padding-top:0em;">
+<div style="margin-right:1em;float:left;margin-left:0em;"><img src="{@docRoot}sdk/images/3.1/resizeable.png" alt="" width="170" target="_android" style="margin-bottom:0;" />
+<div style="padding-left:1.4em;padding-bottom:1em;width:180px;font-size:.9em"><strong>Figure
+4.</strong> Home screen widgets can now be resized.</div></div>
+
+<p><strong>Calendar</strong></p>
+
+<p>Calendar grids are larger, for better readability and more accurate
+touch-targeting. Additionally, users can create a larger viewing area for grids
+by hiding the calendar list controls. Controls in the date picker are
+redesigned, making them easier to see and use.</li>
+</ul>
+
+<p><strong>Contacts</strong></p>
+
+<p>The Contacts app now lets you locate contacts more easily using full text
+search. Search returns matching results from all fields that are stored for a
+contact.
+</p>
+
+<p><strong>Email</strong></p>
+
+<p>When replying or forwarding an HTML message, The Email app now sends both
+plain text and HTML bodies as a multi-part mime message. This ensures that the
+message will be formatted properly for all recipients. Folder prefixes for IMAP
+accounts are now easier to define and manage. To conserve battery power and
+minimize cell data usage, the application now prefetches email from the server
+only when the device is connected to a Wi-Fi access point. </p>
+
+<p>An updated Home screen widget give users quick access to more email. Users
+can touch Email icon at the top of the widget to cycle through labels such as
+Inbox, Unread, and Starred. The widget itself is now resizable, both
+horizontally and vertically.</p>
+
+<h3 id="enterprise">Enterprise support</h3>
+
+<p>Users can now configure an HTTP proxy for each connected Wi-Fi access point.
+This lets administrators work with users to set a proxy hostname, port, and any
+bypass subdomains. This proxy configuration is automatically used by the Browser
+when the Wi-Fi access point is connected, and may optionally be used by other
+apps. The proxy and IP configuration is now backed up and restored across system
+updates and resets.</p>
+
+<p>To meet the needs of tablet users, the platform now allows a "encrypted
+storage card" device policy to be accepted on devices with emulated storage
+cards and encrypted primary storage.</p>
+
+
+<h2 id="DeveloperApis" style="clear:both">New Developer Features</h2>
+
+<p>The Android 3.1 platform adds refinements and new capabilities that
+developers can build on, to create powerful and engaging application experiences
+on tablets and other large-screen devices. </p>
+
+<h3 id="accessory">Open Accessory API for rich interaction with
+peripherals</h3>
+
+<p>Android 3.1 introduces a new API for integrating hardware accessories with
+applications running on the platform. The API provides a way to interact across
+a wide range of peripherals, from robotics controllers to musical equipment,
+exercise bicycles, and more.</p>
+
+<p>The API is based on a new USB (Universal Serial Bus) stack and services
+that are built into the platform. The platform provides services for discovering
+and identifying connected hardware, as well as for notifying interested
+applications that the hardware is available.</p>
+
+<p>When a user plugs in a USB accessory, the platform receives
+identifying information such as product name, accessory type, manufacturer, and
+version. The platform sets up communication with the accessory and uses its
+information to notify and launch a targeted app, if one is available. Optionally,
+an accessory can provide a URL that lets users find and download an
+app that works with the accessory. These discovery features make
+first-time setup easier for the user and ensure that an appropriate application
+is available for interacting with the connected hardware. </p>
+
+<p>For application developers and accessory manufacturers, accessory mode offers
+many new ways to engage users and build powerful interaction experiences with
+connected hardware.</p>
+
+<p>To learn more about how to develop applications that interact with
+accessories, see the <a href="{@docRoot}guide/topics/usb/accessory.html">USB
+Accessory</a> documentation.</p>
+
+<h3 id="host">USB host API</h3>
+
+<p>Android 3.1 provides built-in platform support for USB host mode and exposes
+an API that lets applications manage connected peripherals. On devices that
+support host mode, applications can use the API to identify and communicate with
+connected devices such as audio devices. input devices, communications devices,
+hubs, cameras, and more.</p>
+
+<p>To learn more about how to develop applications that interact with
+USB devices, see the <a href="{@docRoot}guide/topics/usb/host.html">USB
+Host</a> documentation.</p>
+
+<h3 id="inputdevices">Input from mice, joysticks, and gamepads</h3>
+
+<p>Android 3.1 extends the input event system to support a variety of new input
+sources and motion events, across all views and windows. Developers can build on
+these capabilities to let users interact with their applications using mice,
+trackballs, joysticks, gamepads, and other devices, in addition to keyboards and
+touchscreens.</p>
+
+<p>For mouse and trackball input, the platform supports two new motion event
+actions: scroll (horizontal or vertical) such as from a scrollwheel; and hover,
+which reports the location of the mouse when no buttons are pressed.
+Applications can handle these events in any way needed.</p>
+
+<p>For joysticks and gamepads, the platform provides a large number of motion
+axes that applications can use from a given input source, such as X, Y, Hat X,
+Hat Y, rotation, throttle, pressure, size, touch, tool, orientation, and others.
+Developers can also define custom axes if needed, to capture motion in
+additional ways. The platform provides motion events to applications as a batch,
+and applications can query the details of the movements included in the batch,
+for more efficient and precise handling of events.</p>
+
+<p>Applications can query for the list of connected input devices and the motion
+ranges (axes) supported by each device. Applications can also handle multiple
+input and motion events from a single input device. For example, an application
+can use mouse and joystick and mouse event sources from a single input
+device.</p>
+
+<h3 id="resizewidgetsapp">Resizable Home screen widgets</h3>
+
+<p>Developers can now create Home screen widgets that users can resize
+horizontally, vertically, or both. By simply adding an attribute to the
+declaration of a widget, the widget becomes resizable horizontally, vertically,
+or both. This lets users customize the display of the widget content and display
+more of it on their Home screens.</p>
+
+<h3 id="mtp">MTP API for integrating with external cameras</h3>
+
+<p>In Android 3.1, a new MTP (Media Transfer Protocol) API lets developers write
+apps that interact directly with connected cameras and other PTP devices. The
+new API makes it easy for applications to receive notifications when devices are
+attached and removed, manage files and storage on those devices, and transfer
+files and metadata to and from them. The MTP API implements the PTP (Picture
+Transfer Protocol) subset of the MTP specification.</p>
+
+<h3 id="rtp">RTP API, for control over audio streaming sessions</h3>
+
+<p>Android 3.1 exposes an API to its built-in RTP (Real-time Transport Protocol)
+stack, which applications can use to directly manage on-demand or interactive
+data streaming. In particular, apps that provide VOIP, push-to-talk,
+conferencing, and audio streaming can use the API to initiate sessions and
+transmit or receive data streams over any available network.</p>
+
+<h3 id="performance">Performance optimizations</h3>
+
+<p>Android 3.1 includes a variety of performance optimizations that help make
+applications faster and more responsive. Some of the optimizations include:</p>
+
+<ul>
+<li>A new LRU cache class lets applications benefit from efficient caching.
+Applications can use the class to reduce the time spent computing or downloading
+data from the network, while maintaining a sensible memory footprint for the
+cached data.</li>
+<li>The UI framework now supports partial invalidates in hardware-accelerated
+Views, which makes drawing operations in those Views more efficient.</li>
+<li>A new graphics method, {@link android.graphics.Bitmap#setHasAlpha(boolean)
+setHasAlpha()}, allows apps to hint that a given bitmap is opaque. This provides
+an extra performance boost for some types of blits and is especially useful for
+applications that use ARGB_8888 bitmaps.</li>
+</ul>
+
diff --git a/docs/html/sdk/android-3.1.jd b/docs/html/sdk/android-3.1.jd
new file mode 100644
index 0000000..57fe1eb
--- /dev/null
+++ b/docs/html/sdk/android-3.1.jd
@@ -0,0 +1,1053 @@
+page.title=Android 3.1 Platform
+sdk.platform.version=3.1
+sdk.platform.apiLevel=12
+@jd:body
+
+<div id="qv-wrapper">
+<div id="qv">
+
+<h2>In this document</h2>
+<ol>
+ <li><a href="#relnotes">Revisions</a></li>
+ <li><a href="#api">API Overview</a></li>
+ <li><a href="#api-level">API Level</a></li>
+ <li><a href="#apps">Built-in Applications</a></li>
+ <li><a href="#locs">Locales</a></li>
+ <li><a href="#skins">Emulator Skins</a></li>
+</ol>
+
+<h2>Reference</h2>
+<ol>
+<li><a
+href="{@docRoot}sdk/api_diff/11/changes.html">API
+Differences Report »</a> </li>
+</ol>
+
+<h2>See Also</h2>
+<ol>
+ <li><a href="{@docRoot}guide/practices/optimizing-for-3.0.html">Optimizing
+Apps for Android 3.0</a></li>
+</ol>
+
+</div>
+</div>
+
+
+<p><em>API Level:</em> <strong>{@sdkPlatformApiLevel}</strong></p>
+
+<p>For developers, the Android {@sdkPlatformVersion} platform is available as a
+downloadable component for the Android SDK. The downloadable platform includes
+an Android library and system image, as well as a set of emulator skins and
+more. The downloadable platform includes no external 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/index.html">download the SDK Starter Package</a> first.</p>
+
+<p>For a high-level introduction to Android {@sdkPlatformVersion}, see the <a
+href="{@docRoot}sdk/android-{@sdkPlatformVersion}-highlights.html">Platform
+Highlights</a>.</p>
+
+<p class="note"><strong>Reminder:</strong> If you've already published an
+Android application, please test and optimize your application on Android 3.0
+and Android 3.1 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>
+
+
+<h2 id="relnotes">Revisions</h2>
+
+<p>To determine what revision of the Android {@sdkPlatformVersion} platform you
+have installed, refer to the "Installed Packages" listing in the Android SDK and
+AVD Manager.</p>
+
+
+<div class="toggle-content opened" style="padding-left:1em;">
+
+ <p><a href="#" onclick="return toggleContent(this)">
+ <img src="{@docRoot}assets/images/triangle-opened.png"
+class="toggle-content-img" alt="" />
+ Android {@sdkPlatformVersion}, Revision 1</a> <em>(May 2011)</em>
+ </a></p>
+
+ <div class="toggle-content-toggleme" style="padding-left:2em;">
+
+<dl>
+
+<dt>Dependencies:</dt>
+<dd>
+<p>Requires <a href="{@docRoot}sdk/tools-notes.html">SDK Tools r11</a> or
+higher.</p>
+</dd>
+
+</dl>
+
+ </div>
+</div>
+
+
+<h2 id="#api" style="margin-top:1.5em;">API Overview</h2>
+
+<p>The sections below provide a technical overview of what's new for developers
+in Android 3.1, including new features and changes in the framework API since
+the previous version.</p>
+
+<h3 id="usb">USB APIs</h3>
+
+<p>Android 3.1 introduces powerful new APIs for
+integrating connected peripherals with applications running on the platform.
+The APIs are based on a USB (Universal Serial Bus) stack and services that are
+built into the platform, including support for both USB host and device
+interactions. Using the APIs, developers can create applications that are able to
+discover, communicate with, and manage a variety of device types connected over
+USB. </p>
+
+<p>The stack and APIs distinguish two basic types of USB hardware, based on
+whether the platform iself is acting as host or the external hardware is acting
+as host: </p>
+
+<ul>
+<li>A <em>USB device</em> is a piece of connected hardware that depends on the
+Android-powered device to serve as host. For example, most input devices, mice,
+and joysticks are USB devices, as are many cameras, hubs, and so on.</li>
+<li>A <em>USB accessory</em> is a piece of connected hardware that has a USB
+host controller, provides power, and is designed to communicate with
+Android-powered devices over USB, A variety of peripherals can connect as
+accessories, from robotics controllers to musical equipment, exercise bicycles,
+and more.</li>
+</ul>
+
+<p>For both types — USB devices and USB accessories — the
+platform's USB APIs support discovery by intent broadcast when attached or
+detached, as well as standard interfaces, endpoints, and transfer modes
+(control, bulk, and interrupt).</p>
+
+<p>The USB APIs are available in the package {@link android.hardware.usb}. The
+central class is {@link android.hardware.usb.UsbManager}, which provides
+helper methods for identifying and communicating with
+both USB devices and USB accessories. Applications can acquire an instance of
+{@link android.hardware.usb.UsbManager} and then query for the list of attached
+devices or accessories and then communicate with or manage them.
+{@link android.hardware.usb.UsbManager} also declares intent actions that the
+system broadcasts, to announce when a USB device or accessory is attached or
+detached.</p>
+
+<p>Other classes include:</p>
+
+<ul>
+<li>{@link android.hardware.usb.UsbDevice}, a class representing external
+hardware connected as a USB device (with the Android-powered device acting as
+host).</li>
+<li>{@link android.hardware.usb.UsbAccessory}, representing external hardware
+connected as the USB host (with the Android-powered device acting as a USB
+device).</li>
+<li>{@link android.hardware.usb.UsbInterface} and {@link
+android.hardware.usb.UsbEndpoint}, which provide access to standard USB
+interfaces and endpoints for a device.</li>
+<li>{@link android.hardware.usb.UsbDeviceConnection} and {@link
+android.hardware.usb.UsbRequest}, for sending and receiving data and control
+messages to or from a USB device, sychronously and asynchronously.
+<li>{@link android.hardware.usb.UsbConstants}, which provides constants for
+declaring endpoint types, device classes, and so on.</li>
+</ul>
+
+<p>Note that although the USB stack is built into the platform, actual support
+for USB host and open accessory modes on specific devices is determined by
+their manufacturers. In particular, host mode relies on appropriate USB
+controller hardware in the Android-powered device. </p>
+
+<p>Additionally, developers can request filtering on Android Market, such that
+their applications are not availabe to users whose devices do not provide the
+appropriate USB support. To request filtering, add one or both of the elements
+below to the application manifest, as appropriate: </p>
+
+<ul>
+<li>If the application should only be visible to devices that support USB
+host mode (connection of USB devices), declare this element:
+ <p style="margin-left:1.5em;"><code><uses-feature
+ android:name="android.hardware.usb.host"
+ android:required="true"></code></p>
+</li>
+<li>If the application should only be visible to devices that support USB
+accessories (connection of USB hosts), declare this element:
+ <p style="margin-left:1.5em;"><code><uses-feature
+ android:name="android.hardware.usb.accessory"
+ android:required="true"></code></p>
+</li>
+</ul>
+
+<p>For complete information about how to develop applications that interact with
+USB accessories, please see the
+<a href="{@docRoot}guide/topics/usb/index.html">developer documentation</a>.</p>
+
+<p class="note">To look at sample applications that use the USB host API, see <a
+href="{@docRoot}resources/samples/USB/AdbTest/index.html">ADB Test</a> and <a
+href="{@docRoot}resources/samples/USB/MissileLauncher/index.html">Missile
+Launcher</a></p>
+
+<h3>MTP/PTP API</h3>
+
+<p>Android 3.1 exposes a new MTP API that lets applications interact directly
+with connected cameras and other PTP devices. The new API makes it easy for an
+application to receive notifications when devices are attached and removed,
+manage files and storage on those devices, and transfer files and metadata to
+and from them. The MTP API implements the PTP (Picture Transfer Protocol) subset
+of the MTP (Media Transfer Protocol) specification.</p>
+
+<p>The MTP API is available in the {@link android.mtp} package and provides
+these classes: </p>
+
+<ul>
+ <li>The {@link android.mtp.MtpDevice} encapsulates an MTP device that is
+connected over the USB host bus. An application can instantiate an object of
+this type and then use its methods to get information about the device and
+objects stored on it, as well as opening the connection and transferring data.
+Some of the methods include:
+ <ul>
+ <li>{@link android.mtp.MtpDevice#getObjectHandles(int, int, int)
+getObjectHandles()} returns a list of handles for all objects on the device that
+match a specified format and parent. To get information about an object, an
+application can pass a handle to {@link android.mtp.MtpDevice#getObjectInfo(int)
+getObjectInfo()}.</li>
+ <li>{@link android.mtp.MtpDevice#importFile(int, java.lang.String)
+importFile()} lets an application copy data for an object to a file in external
+storage. This call may block for an arbitrary amount of time depending on the
+size of the data and speed of the devices, so should be made from a spearate
+thread.</li>
+ <li>{@link
+android.mtp.MtpDevice#open(android.hardware.usb.UsbDeviceConnection) open()}
+lets an application open a connected MTP/PTP device. </li>
+ <li>{@link android.mtp.MtpDevice#getThumbnail(int) getThumbnail()} returns
+the thumbnail of the object as a byte array. </li>
+ </ul>
+ </li>
+ <li>{@link android.mtp.MtpStorageInfo} holds information about about a storage
+unit on an MTP device, corresponding to the StorageInfo Dataset described in
+section 5.2.2 of the MTP specification. Methods in the class let an application
+get a storage unit’s description string, free space, maximum storage capacity,
+storage ID, and volume identifier.</li>
+ <li>{@link android.mtp.MtpDeviceInfo} holds information about an MTP device
+corresponding to the DeviceInfo Dataset described in section 5.1.1 of the MTP
+specification. Methods in the class let applications get a device’s
+manufacturer, model, serial number, and version.</li>
+ <li>{@link android.mtp.MtpObjectInfo} holds information about an object stored
+on an MTP device, corresponding to the ObjectInfo Dataset described in section
+5.3.1 of the MTP specification. Methods in the class let applications get an
+object’s size, data format, association type, creation date, and thumbnail
+information.</li>
+ <li>{@link android.mtp.MtpConstants} provides constants for declaring MTP file
+format codes, association type, and protection status.</li>
+</ul>
+
+<h3 id="motionevents">Support for new input devices and motion events</h3>
+
+<p>Android 3.1 extends the input subsystem to support new input devices and new
+types of motion events, across all views and windows. Developers can build on
+these capabilities to let users interact with their applications using mice,
+trackballs, joysticks, gamepads, and other devices, in addition to keyboards and
+touchscreens. </p>
+
+<p>For handling mouse, scrollwheel, and trackball input, the platform supports
+two new motion event actions:</p>
+<ul>
+<li>{@link android.view.MotionEvent#ACTION_SCROLL}, which describes the pointer
+location at which a non-touch scroll motion, such as from a mouse scroll wheel,
+took place. In the MotionEvent, the value of the {@link
+android.view.MotionEvent#AXIS_HSCROLL} and {@link
+android.view.MotionEvent#AXIS_VSCROLL} axes specify the relative scroll
+movement. </li>
+<li>{@link android.view.MotionEvent#ACTION_HOVER_MOVE}, reports the current
+position of the mouse when no buttons are pressed, as well as any intermediate
+points since the last <code>HOVER_MOVE</code> event. Hover enter and exit
+notifications are not yet supported.</li>
+</ul>
+
+<p>To support joysticks and gamepads, the {@link android.view.InputDevice} class
+includes these new input device sources:</p>
+<ul>
+<li>{@link android.view.InputDevice#SOURCE_CLASS_JOYSTICK} — the source
+device has joystick axes.</li>
+<li>{@link android.view.InputDevice#SOURCE_CLASS_BUTTON} — the source
+device has buttons or keys.</li>
+<li>{@link android.view.InputDevice#SOURCE_GAMEPAD} — the source device
+has gamepad buttons such as {@link android.view.KeyEvent#KEYCODE_BUTTON_A}
+or {@link android.view.KeyEvent#KEYCODE_BUTTON_B}. Implies
+{@link android.view.InputDevice#SOURCE_CLASS_BUTTON}</li>
+<li>{@link android.view.InputDevice#SOURCE_JOYSTICK} — the source device
+has joystick axes. Implies SOURCE_CLASS_JOYSTICK.</li>
+</ul>
+
+<p>To describe motion events from these new sources, as well as those from mice
+and trackballs, the platform now defines axis codes on {@link
+android.view.MotionEvent}, similar to how it defines key codes on {@link
+android.view.KeyEvent}. New axis codes for joysticks
+and game controllers include
+{@link android.view.MotionEvent#AXIS_HAT_X}, {@link
+android.view.MotionEvent#AXIS_HAT_Y}, {@link
+android.view.MotionEvent#AXIS_RTRIGGER}, {@link
+android.view.MotionEvent#AXIS_ORIENTATION}, {@link
+android.view.MotionEvent#AXIS_THROTTLE}, and many others.
+Existing {@link android.view.MotionEvent} axes are represented by {@link
+android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y},
+{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link
+android.view.MotionEvent#AXIS_SIZE}, {@link
+android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link
+android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link
+android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link
+android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link
+android.view.MotionEvent#AXIS_ORIENTATION}.</p>
+
+<p>Additionally, {@link android.view.MotionEvent} defines a number of generic
+axis codes that are used when the framework does not know how to map a
+particular axis. Specific devices can use the generic axis codes to pass custom
+motion data to applications. For a full list of axes and their intended
+interpretations, see the {@link android.view.MotionEvent} class documentation.
+</p>
+
+<p>The platform provides motion events to applications in batches, so a single
+event may contain a current position and multiple so-called historical movements.
+Applications should use {@link android.view.MotionEvent#getHistorySize()} to get
+the number of historical samples, then retrieve and process all historical
+samples in order using {@link
+android.view.MotionEvent#getHistoricalAxisValue(int, int, int)
+getHistoricalAxisValue()}. After that, applications should process the current
+sample using {@link android.view.MotionEvent#getAxisValue(int) getAxisValue()}.
+</p>
+
+<p>Some axes can be retrieved using special accessor methods. For example,
+instead of calling {@link android.view.MotionEvent#getAxisValue(int)
+getAxisValue()}, applications can call {@link android.view.MotionEvent#getX(int)
+getX()}. Axes that have built-in accessors include {@link
+android.view.MotionEvent#AXIS_X}, {@link android.view.MotionEvent#AXIS_Y},
+{@link android.view.MotionEvent#AXIS_PRESSURE}, {@link
+android.view.MotionEvent#AXIS_SIZE}, {@link
+android.view.MotionEvent#AXIS_TOUCH_MAJOR}, {@link
+android.view.MotionEvent#AXIS_TOUCH_MINOR}, {@link
+android.view.MotionEvent#AXIS_TOOL_MAJOR}, {@link
+android.view.MotionEvent#AXIS_TOOL_MINOR}, and {@link
+android.view.MotionEvent#AXIS_ORIENTATION}.</p>
+
+<p>Each input device has a unique, system-assigned ID and may also provide
+multiple sources. When a device provides multiple sources, more than one source
+can provide axis data using the same axis. For example, a touch event coming
+from the touch source uses the X axis for screen position data, while a joystick
+event coming from the joystick source will use the X axis for the stick position
+instead. For this reason, it's important for applications to interpret axis
+values according to the source from which they originate. When handling a motion
+event, applications should use methods on the {@link android.view.InputDevice}
+class to determine the axes supported by a device or source. Specifically,
+applications can use {@link android.view.InputDevice#getMotionRanges()
+getMotionRanges()} to query for all axes of a device or all axes of a given
+source of the device. In both cases, the range information for axes returned in
+the {@link android.view.InputDevice.MotionRange} object specifies the source for
+each axis value.</p>
+
+<p>Finally, since the motion events from joysticks, gamepads, mice, and
+trackballs are not touch events, the platform adds a new callback method for
+passing them to a {@link android.view.View} as "generic" motion events.
+Specifically, it reports the non-touch motion events to
+{@link android.view.View}s through a call to {@link
+android.view.View#onGenericMotionEvent(android.view.MotionEvent)
+onGenericMotionEvent()}, rather than to {@link
+android.view.View#onTouchEvent(android.view.MotionEvent)
+onTouchEvent()}.</p>
+
+<p>The platform dispatches generic motion events differently, depending on the
+event source class. {@link android.view.InputDevice#SOURCE_CLASS_POINTER} events
+go to the {@link android.view.View} under the pointer, similar to how touch
+events work. All others go to the currently focused {@link android.view.View}.
+For example, this means a {@link android.view.View} must take focus in order to
+receive joystick events. If needed, applications can handle these events at the
+level of Activity or Dialog by implementing {@link
+android.view.View#onGenericMotionEvent(android.view.MotionEvent)
+onGenericMotionEvent()} there instead.</p>
+
+<p class="note">To look at a sample application that uses joystick motion
+events, see <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/
+GameControllerInput.html">GameControllerInput</a> and <a
+href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/view/
+GameView.html">GameView</a>.</p>
+
+<h3>RTP API</h3>
+
+<p>Android 3.1 exposes an API to its built-in RTP (Real-time Transport Protocol)
+stack, which applications can use to manage on-demand or interactive data
+streaming. In particular, apps that provide VOIP, push-to-talk, conferencing,
+and audio streaming can use the API to initiate sessions and transmit or receive
+data streams over any available network.</p>
+
+<p>The RTP API is available in the {@link android.net.rtp} package. Classes
+include: </p>
+<ul>
+<li>{@link android.net.rtp.RtpStream}, the base class of streams that send and
+receive network packets with media payloads over RTP.</li>
+<li>{@link android.net.rtp.AudioStream}, a subclass of {@link
+android.net.rtp.RtpStream} that carries audio payloads over RTP.</li>
+<li>{@link android.net.rtp.AudioGroup}, a local audio hub for managing and
+mixing the device speaker, microphone, and {@link android.net.rtp.AudioStream}.</li>
+<li>{@link android.net.rtp.AudioCodec}, which holds a collection of codecs that
+you define for an {@link android.net.rtp.AudioStream}.</li>
+</ul>
+
+<p>To support audio conferencing and similar usages, an application instantiates
+two classes as endpoints for the stream:</p>
+
+<ul>
+<li>{@link android.net.rtp.AudioStream} specifies a remote endpoint and consists
+of network mapping and a configured {@link android.net.rtp.AudioCodec}.</li>
+<li>{@link android.net.rtp.AudioGroup} represents the local endpoint for one
+or more {@link android.net.rtp.AudioStream}s. The {@link android.net.rtp.AudioGroup} mixes
+all the {@link android.net.rtp.AudioStream}s and optionally interacts with the device
+speaker and the microphone at the same time.</li>
+</ul>
+
+<p>The simplest usage involves a single remote endpoint and local endpoint.
+For more complex usages, please refer to the limitations described for
+{@link android.net.rtp.AudioGroup}.</p>
+
+<p>To use the RTP API, applications must request permission from the user by
+declaring <code><uses-permission
+android:name="android.permission.INTERNET"></code>
+in their manifest files. To acquire the device microphone, the <code><uses-permission
+android:name="android.permission.RECORD_AUDIO"></code> permission is also required.</p>
+
+<h3 id="resizewidgets">Resizable app widgets</h3>
+
+<p>Starting in Android 3.1, developers can make their homescreen widgets
+resizeable — horizontally, vertically, or on both axes. Users touch-hold a
+widget to show its resize handles, then drag the horizontal and/or vertical
+handles to change the size on the layout grid. </p>
+
+<p>Developers can make any Home screen widget resizeable by defining a
+<code>resizeMode</code> attribute in the widget's {@link
+android.appwidget.AppWidgetProviderInfo} metadata. Values for the
+<code>resizeMode</code> attribute include "horizontal", "vertical", and "none".
+To declare a widget as resizeable horizontally and vertically, supply the value
+"horizontal|vertical".
+
+<p>Here's an example: </p>
+
+<pre><appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
+ android:minWidth="294dp"
+ android:minHeight="72dp"
+ android:updatePeriodMillis="86400000"
+ android:previewImage="@drawable/preview"
+ android:initialLayout="@layout/example_appwidget"
+ android:configure="com.example.android.ExampleAppWidgetConfigure"
+ android:resizeMode="horizontal|vertical" >
+</appwidget-provider></pre>
+
+<p>For more information about Home screen widgets, see the <a
+href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a>
+documentation.</p>
+
+<h3 id="animation" style="margin-top:1.25em;">Animation framework</h3>
+
+<ul>
+<li>New ViewPropertyAnimator class
+ <ul>
+ <li>A new {@link android.view.ViewPropertyAnimator} class provides a
+convenient
+way for developers to animate select properties on {@link android.view.View} objects. The class
+automaties and optimizes the animation of the properties and makes it easier to
+manage multiple simulataneous animations on a {@link android.view.View} object.
+<p>Using the {@link android.view.ViewPropertyAnimator} is straightforward. To animate properties for
+a {@link android.view.View}, call {@link android.view.View#animate()} to
+construct a {@link android.view.ViewPropertyAnimator} object for that {@link android.view.View}. Use the
+methods on the {@link android.view.ViewPropertyAnimator} to specify what property to
+animate and how to animate it. For example, to fade the {@link android.view.View} to transparent,
+call <code>alpha(0);</code>. The {@link android.view.ViewPropertyAnimator} object
+handles the details of configuring the underlying {@link
+android.animation.Animator} class and starting it, then rendering the
+animation.</p></li>
+ </ul>
+</li>
+<li>Animation background color
+ <ul>
+ <li>New {@link android.view.animation.Animation#getBackgroundColor()} and
+ {@link android.view.animation.Animation#setBackgroundColor(int)} methods let
+ you get/set the background color behind animations, for window animations
+only. Currently the background must be black, with any desired alpha level.</li>
+ </ul>
+</li>
+<li>Getting animated fraction from <code>ViewAnimator</code>
+ <ul>
+ <li>A new {@link android.animation.ValueAnimator#getAnimatedFraction()}
+method
+lets you get the current animation fraction — the elapsed/interpolated
+fraction used in the most recent frame update — from a {@link
+android.animation.ValueAnimator}.</li>
+ </ul>
+</li>
+</ul>
+
+<h3 "ui">UI framework</h3>
+<ul>
+<li>Forced rendering of a layer
+ <ul>
+ <li>A new {@link android.view.View#buildLayer()} method lets an application
+force a View's layer to be created and the View rendered into it immediately.
+For example, an application could use this method to render a View into its
+layer before starting an animation. If the View is complex, rendering it into
+the layer before starting the animation will avoid skipping frames.</li>
+ </ul>
+</li>
+<li>Camera distance
+ <ul>
+ <li>Applications can use a new method
+{@link android.view.View#setCameraDistance(float)} to set the distance from the
+camera
+to a View. This gives applications improved control over 3D transformations of
+the View, such as rotations. </li>
+ </ul>
+</li>
+<li>Getting a calendar view from a DatePicker
+ <ul>
+ <li>A new {@link android.widget.DatePicker#getCalendarView()} method
+ lets you get a {@link android.widget.CalendarView} from a {@link
+android.widget.DatePicker}
+ instance.</li>
+ </ul>
+</li>
+<li>Getting callbacks when views are detached
+ <ul>
+ <li>A new {@link android.view.View.OnAttachStateChangeListener} lets you
+receive
+callbacks when a View is attached or detached from its window. Use {@link
+android.view.View#addOnAttachStateChangeListener(android.view.View.OnAttachStateChangeListener) addOnAttachStateChangeListener()}
+to add a listener and {@link
+android.view.View#removeOnAttachStateChangeListener(android.view.View.OnAttachStateChangeListener) addOnAttachStateChangeListener()} to remove it.</li>
+ </ul>
+</li>
+<li>Fragment breadcrumb listener, new onInflate() signature
+ <ul>
+ <li>A new method, {@link
+android.app.FragmentBreadCrumbs#setOnBreadCrumbClickListener(android.app.FragmentBreadCrumbs.OnBreadCrumbClickListener) setOnBreadCrumbClickListener()},
+provides a hook to let
+applications intercept fragment-breadcrumb clicks and take any action needed
+before going to the backstack entry or fragment that was clicked. </li>
+ <li>In the {@link android.app.Fragment} class, {@link
+android.app.Fragment#onInflate(android.util.AttributeSet, android.os.Bundle)
+onInflate(attrs, savedInstanceState)} is deprecated. Please use {@link
+android.app.Fragment#onInflate(android.app.Activity, android.util.AttributeSet,
+android.os.Bundle) onInflate(activity, attrs, savedInstanceState)} instead.</li>
+ </ul>
+</li>
+<li>Display search result in new tab
+ <ul>
+ <li>An {@link android.app.SearchManager#EXTRA_NEW_SEARCH} data key for {@link
+android.content.Intent#ACTION_WEB_SEARCH} intents lets you open a search in a
+new browser tab, rather than in an existing one.</li>
+ </ul>
+</li>
+
+<li>Drawable text cursor
+ <ul>
+<li>You can now specify a drawable to use as the text cursor using the new
+resource attribute {@link android.R.attr#textCursorDrawable}.</li>
+ </ul>
+</li>
+<li>Setting displayed child in remote views
+ <ul>
+ <li>A new convenience method, {@link
+android.widget.RemoteViews#setDisplayedChild(int, int) setDisplayedChild(viewId,
+childIndex)}, is available in {@link android.widget.RemoteViews} subclasses, to
+let you set the child displayed in {@link android.widget.ViewAnimator} and
+{@link android.widget.AdapterViewAnimator} subclasses such as {@link
+android.widget.AdapterViewFlipper}, {@link android.widget.StackView}, {@link
+android.widget.ViewFlipper}, and {@link android.widget.ViewSwitcher}.</li>
+ </ul>
+</li>
+<li>Generic keys for gamepads and other input devices
+ <ul>
+ <li>{@link android.view.KeyEvent} adds a range of generic keycodes to
+ accommodate gamepad buttons. The class also adds
+ {@link android.view.KeyEvent#isGamepadButton(int)} and several other
+ helper methods for working with keycodes.</li>
+ </ul>
+</li>
+</ul>
+
+<h3 id="graphics" style="margin-top:1.3em;">Graphics</h3>
+
+<ul>
+<li>Helpers for managing bitmaps
+ <ul>
+ <li>{@link android.graphics.Bitmap#setHasAlpha(boolean)} lets an app indicate that
+all of the pixels in a Bitmap are known to be opaque (false) or that some of the
+pixels may contain non-opaque alpha values (true). Note, for some configs (such
+as RGB_565) this call is ignored, since it does not support per-pixel alpha
+values. This is meant as a drawing hint, as in some cases a bitmap that is known
+to be opaque can take a faster drawing case than one that may have non-opaque
+per-pixel alpha values. </li>
+ <li>{@link android.graphics.Bitmap#getByteCount()} gets a Bitmap's size in
+bytes.</li>
+ <li>{@link android.graphics.Bitmap#getGenerationId()} lets an application find
+out whether a Bitmap has been modified, such as for caching.</li>
+ <li>{@link android.graphics.Bitmap#sameAs(android.graphics.Bitmap)} determines
+whether a given Bitmap differs from the current Bitmap, in dimension,
+configuration, or pixel data. </li>
+ </ul>
+</li>
+<li>Setting camera location and rotation
+ <ul>
+ <li>{@link android.graphics.Camera} adds two new methods {@link
+android.graphics.Camera#rotate(float, float, float) rotate()} and {@link
+android.graphics.Camera#setLocation(float, float, float) setLocation()} for
+control of the
+camera's location, for 3D transformations.</li>
+</ul>
+</li>
+</ul>
+
+<h3 id="network" style="margin-top:1.25em;">Network</h3>
+
+<ul>
+<li>High-performance Wi-Fi lock
+ <ul>
+ <li>A new high-performance Wi-Fi lock lets applications maintain
+high-performance Wi-Fi connections even when the device screen is off.
+Applications that stream music, video, or voice for long periods can acquire the
+high-performance Wi-Fi lock to ensure streaming performance even when the screen
+is off. Because it uses more power, applications should acquire the
+high-performance Wi-Fi when there is a need for a long-running active
+connection.
+<p>To create a high-performance lock, pass {@link
+android.net.wifi.WifiManager#WIFI_MODE_FULL_HIGH_PERF} as the lock mode in a
+call to {@link android.net.wifi.WifiManager#createWifiLock(int,
+java.lang.String) createWifiLock()}.</p></li>
+ </ul>
+</li>
+<li>More traffic stats
+ <ul>
+ <li>Applications can now access statistics about more types of network usage
+using new methods in {@link android.net.TrafficStats}. Applications can use the
+methods to get UDP stats, packet count, TCP transmit/receive payload bytes and
+segments for a given UID.</li>
+ </ul>
+</li>
+<li>SIP auth username
+ <ul>
+ <li>Applications can now get and set the SIP auth username for a profile
+using
+the new methods {@link android.net.sip.SipProfile#getAuthUserName()
+getAuthUserName()} and {@link
+android.net.sip.SipProfile.Builder#setAuthUserName(java.lang.String)
+setAuthUserName()}.</li>
+ </ul>
+</li>
+</ul>
+
+
+<h3 id="download" style="margin-top:1.25em;">Download Manager</h3>
+<ul>
+<li>Handling of completed downloads
+ <ul>
+ <li>Applications can now initiate downloads that notify users only on
+completion. To initiate this type of download, applications pass {@link
+android.app.DownloadManager.Request#VISIBILITY_VISIBLE_NOTIFY_ONLY_COMPLETION}
+in the {@link
+android.app.DownloadManager.Request#setNotificationVisibility(int)
+setNotificationVisibility()} method of
+the a request object.</li>
+ <li>A new method, {@link
+android.app.DownloadManager#addCompletedDownload(java.lang.String,
+java.lang.String, boolean, java.lang.String, java.lang.String, long, boolean)
+addCompletedDownload()}, lets an application add a file to the
+downloads database, so that it can be managed by the Downloads application.</li>
+ </ul>
+</li>
+<li>Show downloads sorted by size
+ <ul>
+ <li>Applications can start the Downloads application in sort-by-size mode by
+adding the new extra {@link
+android.app.DownloadManager#INTENT_EXTRAS_SORT_BY_SIZE} to an {@link
+android.app.DownloadManager#ACTION_VIEW_DOWNLOADS} intent.</li>
+ </ul>
+</li>
+</ul>
+
+<h3 id="ime" style="margin-top:1.25em;">IME framework</h3>
+
+<ul>
+<li>Getting an input method's extra value key
+ <ul><li>The {@link android.view.inputmethod.InputMethodSubtype} adds the
+method
+{@link
+android.view.inputmethod.InputMethodSubtype#containsExtraValueKey(java.lang.String) containsExtraValueKey()} to check whether an ExtraValue string is stored
+for the subtype and
+the method {@link
+android.view.inputmethod.InputMethodSubtype#getExtraValueOf(java.lang.String)
+getExtraValueOf()} to extract a specific key value from the ExtraValue hashmap.
+</li>
+ </ul>
+</li>
+</ul>
+
+<h3 id="media" style="margin-top:1.25em;">Media</h3>
+
+<ul>
+<li>New streaming audio formats
+ <ul>
+ <li>The media framework adds built-in support for raw ADTS AAC content, for
+improved streaming audio, as well as support for FLAC audio, for highest quality
+(lossless) compressed audio content. See the <a
+href="{@docRoot}guide/appendix/media-formats.html">Supported Media Formats</a>
+document for more information.</p></li>
+ </ul>
+</li>
+</ul>
+
+<h3 id="launchcontrols" style="margin-top:1.25em;">Launch controls on stopped
+applications</h3>
+
+<p>Starting from Android 3.1, the system's package manager keeps track of
+applications that are in a stopped state and provides a means of controlling
+their launch from background processes and other applications.</p>
+
+<p>Note that an application's stopped state is not the same as an Activity's
+stopped state. The system manages those two stopped states separately.</p>
+
+<p>The platform defines two new intent flags that let a sender specify
+whether the Intent should be allowed to activate components in stopped
+application.</p>
+
+<ul>
+<li>{@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES} —
+Include intent filters of stopped applications in the list of potential targets
+to resolve against. </li>
+<li>{@link android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES} —
+Exclude intent filters of stopped applications from the list of potential
+targets.</li>
+</ul>
+
+<p>When neither or both of these flags is defined in an intent, the default
+behavior is to include filters of stopped applications in the list of
+potential targets.</p>
+
+<p>Note that the system adds {@link
+android.content.Intent#FLAG_EXCLUDE_STOPPED_PACKAGES} <em>to all broadcast
+intents</em>. It does this to prevent broadcasts from background services from
+inadvertently or unnecessarily launching components of stoppped applications.
+A background service or application can override this behavior by adding the
+{@link android.content.Intent#FLAG_INCLUDE_STOPPED_PACKAGES} flag to broadcast
+intents that should be allowed to activate stopped applications.</p>
+
+<p>Applications are in a stopped state when they are first installed but are not
+yet launched and when they are manually stopped by the user (in Manage
+Applications).</p>
+
+<h3 id="installnotification">Notification of application first launch and upgrade</h3>
+
+<p>The platform adds improved notification of application first launch and
+upgrades through two new intent actions:</p>
+
+<ul>
+<li>{@link android.content.Intent#ACTION_PACKAGE_FIRST_LAUNCH} — Sent to
+the installer package of an application when that application is first launched
+(that is, the first time it is moved out of a stopped state). The data
+contains the name of the package. </li>
+
+<li>{@link android.content.Intent#ACTION_MY_PACKAGE_REPLACED} — Notifies
+an application that it was updated, with a new version was installed over
+an existing version. This is only sent to the application that was replaced. It
+does not contain any additional data. To receive it, declare an intent filter
+for this action. You can use the intent to trigger code that helps get your
+application back in proper running shape after an upgrade.
+
+<p>This intent is sent directly to the application, but only if the application
+was upgraded while it was in started state (not in a stopped state).</p></li>
+
+</ul>
+
+<h3 if="other">Core utilities</h3>
+
+<ul>
+<li>LRU cache
+ <ul>
+ <li>A new {@link android.util.LruCache} class lets your applications benefit
+from efficient caching. Applications can use the class to reduce the time spent
+computing or downloading data from the network, while maintaining a sensible
+memory footprint for the cached data.{@link android.util.LruCache} is a cache
+that holds strong references to a limited number of values. Each time a value is
+accessed, it is moved to the head of a queue. When a value is added to a full
+cache, the value at the end of that queue is evicted and may become eligible for
+garbage collection.</li>
+ </ul>
+</li>
+<li>File descriptor as <code>int</code>
+ <ul>
+ <li>You can now get the native file descriptor int for a {@link
+android.os.ParcelFileDescriptor} using either of the new methods {@link
+android.os.ParcelFileDescriptor#getFd()} or {@link
+android.os.ParcelFileDescriptor#detachFd()}. </li>
+ </ul>
+</li>
+</ul>
+
+
+
+
+
+
+<h3 id="webkit" style="margin-top:1.25em;">WebKit</h3>
+
+<ul>
+
+<li>File scheme cookies
+ <ul>
+ <li>The {@link android.webkit.CookieManager} now supports cookies that use
+the
+<code>file:</code> URI scheme. You can use {@link
+android.webkit.CookieManager#setAcceptFileSchemeCookies(boolean)
+setAcceptFileSchemeCookies()} to
+enable/disable support for file scheme cookies, before constructing an instance
+of <code>WebView</code> or <code>CookieManager</code>. In a
+<code>CookieManager</code> instance, you can check whether file scheme cookies
+is enabled by calling {@link
+android.webkit.CookieManager#allowFileSchemeCookies()}.</li>
+ </ul>
+</li>
+<li>Notification of login request
+ <ul>
+ <li>To support the browser autologin features introduced in Android 3.0, the
+new
+method {@link
+android.webkit.WebViewClient#onReceivedLoginRequest(android.webkit.WebView,java.lang.String, java.lang.String, java.lang.String) onReceivedLoginRequest()}
+notifies the host
+application that an autologin request for the user was processed. </li>
+ </ul>
+</li>
+<li>Removed classes and interfaces
+ <ul>
+ <li>Several classes and interfaces were removed from the public API, after
+previously being in deprecated state. See the <a
+href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API
+Differences Report</a> for more information.</p></li>
+ </ul>
+ </li>
+</ul>
+
+
+
+<h3 id="browser" style="margin-top:1.25em;">Browser</h3>
+
+<p>The Browser application adds the following features to support web
+applications:</p>
+
+<ul>
+<li>Support for inline playback of video embedded in HTML5
+<code><video></code> tag. Playback is hardware-accelerated where possible.
+</li>
+<li>Layer support for fixed position elements for all sites (mobile and
+desktop).</li>
+</ul>
+
+
+
+
+
+<h3 id="features">New feature constants</h3>
+
+<p>The platform adds new hardware feature constants that developers can declare
+in their application manifests, to inform external entities such as Android
+Market of the application's requirement for new hardware capabilities supported
+in this version of the platform. Developers declare these and other feature
+constants in <a
+href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
+<uses-feature>}</a> manifest elements.
+
+<ul>
+ <li>{@link android.content.pm.PackageManager#FEATURE_USB_ACCESSORY
+android.hardware.usb.accessory} — The application uses the <a href="#usb">USB
+API</a> to communicate with external hardware devices connected over USB and
+function as hosts.</li>
+ <li>{@link android.content.pm.PackageManager#FEATURE_USB_HOST
+android.hardware.usb.host} — The application uses the <a href="#usb">USB API</a>
+to communicate with external hardware devices connected over USB and function as
+devices.</li>
+</ul>
+
+<p>Android Market filters applications based on features declared in <a
+href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
+<uses-feature>}</a> manifest elements. For more information about
+declaring features in an application manifest, read <a
+href="{docRoot}guide/appendix/market-filters.html">Android Market
+Filters</a>.</p>
+
+
+
+<h3 id="api-diff">API Differences Report</h3>
+
+<p>For a detailed view of all API changes in Android {@sdkPlatformVersion} (API
+Level
+{@sdkPlatformApiLevel}), see the <a
+href="{@docRoot}sdk/api_diff/{@sdkPlatformApiLevel}/changes.html">API
+Differences Report</a>.</p>
+
+
+
+
+
+<h2 id="api-level">API Level</h2>
+
+<p>The Android {@sdkPlatformVersion} platform delivers an updated version of
+the framework API. The Android {@sdkPlatformVersion} API
+is assigned an integer identifier —
+<strong>{@sdkPlatformApiLevel}</strong> — that is
+stored in the system itself. This identifier, called the "API Level", allows the
+system to correctly determine whether an application is compatible with
+the system, prior to installing the application. </p>
+
+<p>To use APIs introduced in Android {@sdkPlatformVersion} in your application,
+you need compile the application against the Android library that is provided in
+the Android {@sdkPlatformVersion} SDK platform. Depending on your needs, you
+might
+also need to add an <code>android:minSdkVersion="{@sdkPlatformApiLevel}"</code>
+attribute to the <code><uses-sdk></code> element in the application's
+manifest.</p>
+
+<p>For more information about how to use API Level, see the <a
+href="{@docRoot}guide/appendix/api-levels.html">API Levels</a> document. </p>
+
+
+<h2 id="apps">Built-in Applications</h2>
+
+<p>The system image included in the downloadable platform provides these
+built-in applications:</p>
+
+<table style="border:0;padding-bottom:0;margin-bottom:0;">
+<tr>
+<td style="border:0;padding-bottom:0;margin-bottom:0;">
+<ul>
+<li>API Demos</li>
+<li>Browser</li>
+<li>Calculator</li>
+<li>Camera</li>
+<li>Clock</li>
+<li>Contacts</li>
+<li>Custom Locale</li>
+<li>Dev Tools</li>
+<li>Downloads</li>
+<li>Email</li>
+</ul>
+</td>
+<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
+<ul>
+<li>Gallery</li>
+<li>Gestures Builder</li>
+<li>Messaging</li>
+<li>Music</li>
+<li>Search</li>
+<li>Settings</li>
+<li>Spare Parts</li>
+<li>Speech Recorder</li>
+<li>Widget Preview</li>
+</ul>
+</td>
+</tr>
+</table>
+
+
+<h2 id="locs" style="margin-top:.75em;">Locales</h2>
+
+<p>The system image included in the downloadable SDK platform provides a variety
+of
+built-in locales. In some cases, region-specific strings are available for the
+locales. In other cases, a default version of the language is used. The
+languages that are available in the Android 3.0 system
+image are listed below (with <em>language</em>_<em>country/region</em> locale
+descriptor).</p>
+
+<table style="border:0;padding-bottom:0;margin-bottom:0;">
+<tr>
+<td style="border:0;padding-bottom:0;margin-bottom:0;">
+<ul>
+<li>Arabic, Egypt (ar_EG)</li>
+<li>Arabic, Israel (ar_IL)</li>
+<li>Bulgarian, Bulgaria (bg_BG)</li>
+<li>Catalan, Spain (ca_ES)</li>
+<li>Czech, Czech Republic (cs_CZ)</li>
+<li>Danish, Denmark(da_DK)</li>
+<li>German, Austria (de_AT)</li>
+<li>German, Switzerland (de_CH)</li>
+<li>German, Germany (de_DE)</li>
+<li>German, Liechtenstein (de_LI)</li>
+<li>Greek, Greece (el_GR)</li>
+<li>English, Australia (en_AU)</li>
+<li>English, Canada (en_CA)</li>
+<li>English, Britain (en_GB)</li>
+<li>English, Ireland (en_IE)</li>
+<li>English, India (en_IN)</li>
+<li>English, New Zealand (en_NZ)</li>
+<li>English, Singapore(en_SG)</li>
+<li>English, US (en_US)</li>
+<li>English, Zimbabwe (en_ZA)</li>
+<li>Spanish (es_ES)</li>
+<li>Spanish, US (es_US)</li>
+<li>Finnish, Finland (fi_FI)</li>
+<li>French, Belgium (fr_BE)</li>
+<li>French, Canada (fr_CA)</li>
+<li>French, Switzerland (fr_CH)</li>
+<li>French, France (fr_FR)</li>
+<li>Hebrew, Israel (he_IL)</li>
+<li>Hindi, India (hi_IN)</li>
+</ul>
+</td>
+<td style="border:0;padding-bottom:0;margin-bottom:0;padding-left:5em;">
+<li>Croatian, Croatia (hr_HR)</li>
+<li>Hungarian, Hungary (hu_HU)</li>
+<li>Indonesian, Indonesia (id_ID)</li>
+<li>Italian, Switzerland (it_CH)</li>
+<li>Italian, Italy (it_IT)</li>
+<li>Japanese (ja_JP)</li>
+<li>Korean (ko_KR)</li>
+<li>Lithuanian, Lithuania (lt_LT)</li>
+<li>Latvian, Latvia (lv_LV)</li>
+<li>Norwegian bokmål, Norway (nb_NO)</li>
+<li>Dutch, Belgium (nl_BE)</li>
+<li>Dutch, Netherlands (nl_NL)</li>
+<li>Polish (pl_PL)</li>
+<li>Portuguese, Brazil (pt_BR)</li>
+<li>Portuguese, Portugal (pt_PT)</li>
+<li>Romanian, Romania (ro_RO)</li>
+<li>Russian (ru_RU)</li></li>
+<li>Slovak, Slovakia (sk_SK)</li>
+<li>Slovenian, Slovenia (sl_SI)</li>
+<li>Serbian (sr_RS)</li>
+<li>Swedish, Sweden (sv_SE)</li>
+<li>Thai, Thailand (th_TH)</li>
+<li>Tagalog, Philippines (tl_PH)</li>
+<li>Turkish, Turkey (tr_TR)</li>
+<li>Ukrainian, Ukraine (uk_UA)</li>
+<li>Vietnamese, Vietnam (vi_VN)</li>
+<li>Chinese, PRC (zh_CN)</li>
+<li>Chinese, Taiwan (zh_TW)</li>
+</td>
+</tr>
+</table>
+
+<p class="note"><strong>Note:</strong> The Android platform may support more
+locales than are included in the SDK system image. All of the supported locales
+are available in the <a href="http://source.android.com/">Android Open Source
+Project</a>.</p>
+
+<h2 id="skins">Emulator Skins</h2>
+
+<p>The downloadable platform includes the following emulator skin:</p>
+
+<ul>
+ <li>
+ WXGA (1280x800, medium density, xlarge screen)
+ </li>
+</ul>
+
+<p>For more information about how to develop an application that displays
+and functions properly on all Android-powered devices, see <a
+href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple
+Screens</a>.</p>
\ No newline at end of file
diff --git a/docs/html/sdk/images/3.1/controls.png b/docs/html/sdk/images/3.1/controls.png
new file mode 100644
index 0000000..e0ca1f8
--- /dev/null
+++ b/docs/html/sdk/images/3.1/controls.png
Binary files differ
diff --git a/docs/html/sdk/images/3.1/home.png b/docs/html/sdk/images/3.1/home.png
new file mode 100644
index 0000000..ea0a75a
--- /dev/null
+++ b/docs/html/sdk/images/3.1/home.png
Binary files differ
diff --git a/docs/html/sdk/images/3.1/home_full.png b/docs/html/sdk/images/3.1/home_full.png
new file mode 100644
index 0000000..2b8e85e
--- /dev/null
+++ b/docs/html/sdk/images/3.1/home_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.1/resizeable.png b/docs/html/sdk/images/3.1/resizeable.png
new file mode 100644
index 0000000..c9f5e8e
--- /dev/null
+++ b/docs/html/sdk/images/3.1/resizeable.png
Binary files differ
diff --git a/docs/html/sdk/images/3.1/tasks.png b/docs/html/sdk/images/3.1/tasks.png
new file mode 100644
index 0000000..89d69e5
--- /dev/null
+++ b/docs/html/sdk/images/3.1/tasks.png
Binary files differ
diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd
index 7f6f0105..7c1c86d 100644
--- a/docs/html/sdk/index.jd
+++ b/docs/html/sdk/index.jd
@@ -1,21 +1,21 @@
page.title=Android SDK
sdk.redirect=0
-sdk.win_installer=installer_r10-windows.exe
-sdk.win_installer_bytes=32878481
-sdk.win_installer_checksum=8ffa2dd734829d0bbd3ea601b50b36c7
+sdk.win_installer=installer_r11-windows.exe
+sdk.win_installer_bytes=32883649
+sdk.win_installer_checksum=3dc8a29ae5afed97b40910ef153caa2b
-sdk.win_download=android-sdk_r10-windows.zip
-sdk.win_bytes=32832260
-sdk.win_checksum=1e42b8f528d9ca6d9b887c58c6f1b9a2
+sdk.win_download=android-sdk_r11-windows.zip
+sdk.win_bytes=32837554
+sdk.win_checksum=0a2c52b8f8d97a4871ce8b3eb38e3072
-sdk.mac_download=android-sdk_r10-mac_x86.zip
-sdk.mac_bytes=28847132
-sdk.mac_checksum=e3aa5578a6553b69cc36659c9505be3f
+sdk.mac_download=android-sdk_r11-mac_x86.zip
+sdk.mac_bytes=28844968
+sdk.mac_checksum=85bed5ed25aea51f6a447a674d637d1e
-sdk.linux_download=android-sdk_r10-linux_x86.tgz
-sdk.linux_bytes=26981997
-sdk.linux_checksum=c022dda3a56c8a67698e6a39b0b1a4e0
+sdk.linux_download=android-sdk_r11-linux_x86.tgz
+sdk.linux_bytes=26984929
+sdk.linux_checksum=026c67f82627a3a70efb197ca3360d0a
@jd:body
diff --git a/docs/html/sdk/sdk_toc.cs b/docs/html/sdk/sdk_toc.cs
index 3240b57..11f29b1 100644
--- a/docs/html/sdk/sdk_toc.cs
+++ b/docs/html/sdk/sdk_toc.cs
@@ -77,37 +77,59 @@
</ul>
<ul>
<li class="toggle-list">
+ <div><a href="<?cs var:toroot ?>sdk/android-3.1.html">
+ <span class="en">Android 3.1 Platform</span></a> <span class="new">new!</span></div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>sdk/android-3.1-highlights.html">Platform Highlights</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/api_diff/12/changes.html">API Differences Report »</a></li>
+ </ul>
+ </li>
+ <li class="toggle-list">
<div><a href="<?cs var:toroot ?>sdk/android-3.0.html">
- <span class="en">Android 3.0 Platform</span></a> <span class="new">new!</span></div>
+ <span class="en">Android 3.0 Platform</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/android-3.0-highlights.html">Platform Highlights</a></li>
<li><a href="<?cs var:toroot ?>sdk/api_diff/11/changes.html">API Differences Report »</a></li>
</ul>
</li>
+ <li><a href="<?cs var:toroot ?>sdk/android-2.3.4.html">Android 2.3.4 Platform</span></a> <span class="new">new!</span></li>
<li class="toggle-list">
<div><a href="<?cs var:toroot ?>sdk/android-2.3.3.html">
- <span class="en">Android 2.3.3 Platform</span></a> <span class="new">new!</span></div>
+ <span class="en">Android 2.3.3 Platform</span></a></div>
<ul>
<li><a href="<?cs var:toroot ?>sdk/api_diff/10/changes.html">API Differences Report »</a></li>
</ul>
</li>
<li class="toggle-list">
- <div><a href="<?cs var:toroot ?>sdk/android-2.3.html">
- <span class="en">Android 2.3 Platform</span></a></div>
+ <div><a href="<?cs var:toroot ?>sdk/android-2.2.html">
+ <span class="en">Android 2.2 Platform</span></a></div>
<ul>
- <li><a href="<?cs var:toroot ?>sdk/android-2.3-highlights.html">Platform Highlights</a></li>
- <li><a href="<?cs var:toroot ?>sdk/api_diff/9/changes.html">API Differences Report »</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/android-2.2-highlights.html">Platform Highlights</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/api_diff/8/changes.html">API Differences Report »</a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>sdk/android-2.2.html">Android 2.2 Platform</a></li>
- <li><a href="<?cs var:toroot ?>sdk/android-2.1.html">Android 2.1 Platform</a></li>
- <li><a href="<?cs var:toroot ?>sdk/android-1.6.html">Android 1.6 Platform</a></li>
- <li><a href="<?cs var:toroot ?>sdk/android-1.5.html">Android 1.5 Platform</a></li>
<li class="toggle-list">
- <div><a href="#" onclick="toggle(this.parentNode.parentNode,true); return false;">Older Platforms</a></div>
+ <div><a href="<?cs var:toroot ?>sdk/android-2.1.html">
+ <span class="en">Android 2.1 Platform</span></a></div>
<ul>
+ <li><a href="<?cs var:toroot ?>sdk/api_diff/7/changes.html">API Differences Report »</a></li>
+ </ul>
+ </li>
+ <li class="toggle-list">
+ <div><a href="#" onclick="toggle(this.parentNode.parentNode,true); return false;">Other Platforms</a></div>
+ <ul>
+ <li class="toggle-list">
+ <div><a href="<?cs var:toroot ?>sdk/android-2.3.html">
+ <span class="en">Android 2.3 Platform</span></a></div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>sdk/android-2.3-highlights.html">Platform Highlights</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/api_diff/9/changes.html">API Differences Report »</a></li>
+ </ul>
+ </li>
<li><a href="<?cs var:toroot ?>sdk/android-2.0.1.html">Android 2.0.1 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-2.0.html">Android 2.0 Platform</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/android-1.6.html">Android 1.6 Platform</a></li>
+ <li><a href="<?cs var:toroot ?>sdk/android-1.5.html">Android 1.5 Platform</a></li>
<li><a href="<?cs var:toroot ?>sdk/android-1.1.html">Android 1.1 Platform</a></li>
</ul>
</li>
diff --git a/docs/html/sdk/tools-notes.jd b/docs/html/sdk/tools-notes.jd
index 354fec9..64c8f2a 100644
--- a/docs/html/sdk/tools-notes.jd
+++ b/docs/html/sdk/tools-notes.jd
@@ -65,7 +65,7 @@
<div class="toggleable opened">
<a href="#" onclick="return toggleDiv(this)">
<img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-img" height="9px" width="9px" />
-SDK Tools, Revision 10</a> <em>(February 2011)</em>
+SDK Tools, Revision 11</a> <em>(May 2011)</em>
<div class="toggleme">
<dl>
<dt>Dependencies:</dt>
diff --git a/docs/html/videos/index.jd b/docs/html/videos/index.jd
index 0274095..50bdb46 100644
--- a/docs/html/videos/index.jd
+++ b/docs/html/videos/index.jd
@@ -62,7 +62,7 @@
*/
function loadVideo(id, title, autoplay) {
if($("." + id).hasClass("noplay")) {
- console.log("noplay");
+ //console.log("noplay");
autoplay = false;
$("." + id).removeClass("noplay");
}
@@ -255,42 +255,59 @@
* @param videoId The ID of the video to click
*/
function clickVideo(videoId) {
+ if (!isAlphaNumeric(videoId)) {
+ clickDefaultVideo();
+ return;
+ }
+
if ($("." + videoId).length != 0) { // if we find the video, click it and return
- $("." + videoId).addClass("noplay"); // add class to indicate we should NOT autoplay (class removed by loadVideo)
- $("." + videoId + ":first").click();
- return;
+ $("." + videoId).addClass("noplay"); // add class to indicate we should NOT autoplay (class removed by loadVideo)
+ $("." + videoId + ":first").click();
+ return;
} else { // if we don't find it, increment clickVideoAttempts
- console.log("video NOT found: " + videoId);
- clickVideoAttempts++;
+ console.log("video NOT found: " + videoId);
+ clickVideoAttempts++;
}
// if we don't find it after 20 attempts (2 seconds), click the first feature video
if (clickVideoAttempts > 10) {
- console.log("video never found, clicking default...");
+ console.log("video never found, clicking default...");
clickVideoAttempts = 0;
clickDefaultVideo();
} else { // try again after 100 milliseconds
- setTimeout('clickVideo("'+videoId+'")', 100);
+ setTimeout('clickVideo("' + videoId + '")', 100);
+ }
+}
+
+/* returns true if the provided text is alphanumeric, false otherwise
+ TODO: move this to the dev site js library */
+function isAlphaNumeric(text){
+ var regex=/^[0-9A-Za-z]+$/; //^[a-zA-z]+$/
+ if(regex.test(text)){
+ return true;
+ } else {
+ console.log("Bogus video ID");
+ return false;
}
}
/* Click the default video that should be loaded on page load (the first video in the featured list) */
function clickDefaultVideo() {
- if ($("#mainBodyRight .videoPreviews a:first").length != 0) {
- var videoId = $("#mainBodyRight .videoPreviews a:first").attr("class");
+ if ($("#mainBodyRight .videoPreviews a:first").length != 0) {
+ var videoId = $("#mainBodyRight .videoPreviews a:first").attr("class");
$("." + videoId).addClass("noplay"); // add class to indicate we should NOT autoplay (class removed by loadVideo)
- $("." + videoId + ":first").click();
- return;
+ $("." + videoId + ":first").click();
+ return;
} else { // if we don't find it, increment clickVideoAttempts
- console.log("default video NOT found");
- clickVideoAttempts++;
+ console.log("default video NOT found");
+ clickVideoAttempts++;
}
// if we don't find it after 50 attempts (5 seconds), just fail
if (clickVideoAttempts > 50) {
- console.log("default video never found...");
+ console.log("default video never found...");
} else { // try again after 100 milliseconds
- setTimeout('clickDefaultVideo()', 100);
+ setTimeout('clickDefaultVideo()', 100);
}
}
</script>
