Merge "docs: fix broken links and add new sitemap text file" into jb-mr1-dev
diff --git a/core/java/android/view/ViewPropertyAnimator.java b/core/java/android/view/ViewPropertyAnimator.java
index d8db14c..22f98b7 100644
--- a/core/java/android/view/ViewPropertyAnimator.java
+++ b/core/java/android/view/ViewPropertyAnimator.java
@@ -701,7 +701,7 @@
* view.animate().x(0);
* }
* };
- * view.animate().x(200).onEnd(endAction);
+ * view.animate().x(200).withEndAction(endAction);
* </pre>
*
* @param runnable The action to run when the next animation ends.
diff --git a/docs/downloads/training/ThreadSample.zip b/docs/downloads/training/ThreadSample.zip
new file mode 100644
index 0000000..bdc3ccf
--- /dev/null
+++ b/docs/downloads/training/ThreadSample.zip
Binary files differ
diff --git a/docs/html/about/dashboards/index.jd b/docs/html/about/dashboards/index.jd
index 7282dbb..aa0e010 100644
--- a/docs/html/about/dashboards/index.jd
+++ b/docs/html/about/dashboards/index.jd
@@ -30,33 +30,33 @@
<th>API</th>
<th>Distribution</th>
</tr>
-<tr><td><a href="/about/versions/android-1.5.html">1.5</a></td><td>Cupcake</td> <td>3</td><td>0.1%</td></tr>
-<tr><td><a href="/about/versions/android-1.6.html">1.6</a></td><td>Donut</td> <td>4</td><td>0.3%</td></tr>
-<tr><td><a href="/about/versions/android-2.1.html">2.1</a></td><td>Eclair</td> <td>7</td><td>2.7%</td></tr>
-<tr><td><a href="/about/versions/android-2.2.html">2.2</a></td><td>Froyo</td> <td>8</td><td>10.3%</td></tr>
+<tr><td><a href="/about/versions/android-1.6.html">1.6</a></td><td>Donut</td> <td>4</td><td>0.2%</td></tr>
+<tr><td><a href="/about/versions/android-2.1.html">2.1</a></td><td>Eclair</td> <td>7</td><td>2.4%</td></tr>
+<tr><td><a href="/about/versions/android-2.2.html">2.2</a></td><td>Froyo</td> <td>8</td><td>9.0%</td></tr>
<tr><td><a href="/about/versions/android-2.3.html">2.3 - 2.3.2</a>
</td><td rowspan="2">Gingerbread</td> <td>9</td><td>0.2%</td></tr>
<tr><td><a href="/about/versions/android-2.3.3.html">2.3.3 - 2.3.7
- </a></td><!-- Gingerbread --> <td>10</td><td>50.6%</td></tr>
+ </a></td><!-- Gingerbread --> <td>10</td><td>47.4%</td></tr>
<tr><td><a href="/about/versions/android-3.1.html">3.1</a></td>
<td rowspan="2">Honeycomb</td> <td>12</td><td>0.4%</td></tr>
-<tr><td><a href="/about/versions/android-3.2.html">3.2</a></td> <!-- Honeycomb --><td>13</td><td>1.2%</td></tr>
+<tr><td><a href="/about/versions/android-3.2.html">3.2</a></td> <!-- Honeycomb --><td>13</td><td>1.1%</td></tr>
<tr><td><a href="/about/versions/android-4.0.3.html">4.0.3 - 4.0.4</a></td>
- <td>Ice Cream Sandwich</td><td>15</td><td>27.5%</td></tr>
+ <td>Ice Cream Sandwich</td><td>15</td><td>29.1%</td></tr>
<tr><td><a href="/about/versions/android-4.1.html">4.1</a></td>
- <td rowspan="2">Jelly Bean</td><td>16</td><td>5.9%</td></tr>
-<tr><td><a href="/about/versions/android-4.2.html">4.2</a></td><!--Jelly Bean--> <td>17</td><td>0.8%</td></tr>
+ <td rowspan="2">Jelly Bean</td><td>16</td><td>9.0%</td></tr>
+<tr><td><a href="/about/versions/android-4.2.html">4.2</a></td><!--Jelly Bean--> <td>17</td><td>1.2%</td></tr>
</table>
</div>
<div class="col-8" style="margin-right:0">
<img alt=""
-src="http://chart.apis.google.com/chart?&cht=p&chs=460x245&chf=bg,s,00000000&chd=t:3.1,10.3,50.8,1.6,27.5,6.7&chl=Eclair%20%26%20older|Froyo|Gingerbread|Honeycomb|Ice%20Cream%20Sandwich|Jelly%20Bean&chco=c4df9b,6fad0c" />
+src="http://chart.apis.google.com/chart?&cht=p&chs=460x245&chf=bg,s,00000000&chd=t:2.6,9.0,47.6,1.5,29.1,10.2&chl=Eclair%20%26%20older|Froyo|Gingerbread|Honeycomb|Ice%20Cream%20Sandwich|Jelly%20Bean&chco=c4df9b,6fad0c"
+/>
</div><!-- end dashboard-panel -->
-<p style="clear:both"><em>Data collected during a 14-day period ending on December 3, 2012</em></p>
+<p style="clear:both"><em>Data collected during a 14-day period ending on January 3, 2013</em></p>
<!--
<p style="font-size:.9em">* <em>Other: 0.1% of devices running obsolete versions</em></p>
-->
@@ -81,9 +81,9 @@
Google Play within a 14-day period ending on the date indicated on the x-axis.</p>
<img alt="" height="250" width="660"
-src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chf=bg,s,00000000&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C06/01%7C06/15%7C07/01%7C07/15%7C08/01%7C08/15%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C1%3A%7C2012%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C2012%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:99.1,99.2,99.2,99.2,99.2,99.2,99.3,99.4,99.5,99.5,99.5,99.6,100.0|93.9,94.2,94.5,94.7,95.0,95.2,95.6,95.8,96.1,96.3,96.4,96.7,96.9|74.8,75.9,77.1,78.3,79.5,80.4,81.4,82.3,83.2,83.8,84.7,85.6,86.4|9.8,11.3,13.0,15.7,18.9,21.2,23.7,25.5,27.4,28.7,31.1,33.0,35.4|7.1,8.7,10.6,13.3,16.6,19.0,21.5,23.5,25.5,26.8,29.4,31.4,33.8|0.0,0.0,0.0,0.0,0.8,0.9,1.1,1.4,1.8,2.1,3.2,4.8,6.5&chm=b,c3df9b,0,1,0|tFroyo,689326,1,0,15,,t::-5|b,b4db77,1,2,0|tGingerbread,547a19,2,0,15,,t::-5|b,a5db51,2,3,0|b,96dd28,3,4,0|tIce%20Cream%20Sandwich,293f07,4,2,15,,t::-5|b,83c916,4,5,0|B,6fad0c,5,6,0&chg=7,25&chdl=Eclair|Froyo|Gingerbread|Honeycomb|Ice%20Cream%20Sandwich|Jelly%20Bean&chco=add274,9dd14f,8ece2a,7ab61c,659b11,507d08"
+src="http://chart.apis.google.com/chart?&cht=lc&chs=660x250&chxt=x,x,y,r&chf=bg,s,00000000&chxr=0,0,12|1,0,12|2,0,100|3,0,100&chxl=0%3A%7C07/01%7C07/15%7C08/01%7C08/15%7C09/01%7C09/15%7C10/01%7C10/15%7C11/01%7C11/15%7C12/01%7C12/15%7C01/01%7C1%3A%7C2012%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C%7C2013%7C2%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25%7C3%3A%7C0%25%7C25%25%7C50%25%7C75%25%7C100%25&chxp=0,0,1,2,3,4,5,6,7,8,9,10,11,12&chxtc=0,5&chd=t:99.2,99.2,99.2,99.2,99.3,99.4,99.5,99.5,99.5,99.6,100.0,100.0,100.0|94.5,94.7,95.0,95.2,95.6,95.8,96.1,96.3,96.4,96.7,96.9,97.2,97.4|77.1,78.3,79.5,80.4,81.4,82.3,83.2,83.8,84.7,85.6,86.4,87.0,88.2|13.0,15.7,18.9,21.2,23.7,25.5,27.4,28.7,31.1,33.0,35.4,36.8,40.3|10.6,13.3,16.6,19.0,21.5,23.5,25.5,26.8,29.4,31.4,33.8,35.2,38.8|0.0,0.0,0.8,0.9,1.1,1.4,1.8,2.1,3.2,4.8,6.5,7.5,9.9&chm=b,c3df9b,0,1,0|tFroyo,689326,1,0,15,,t::-5|b,b4db77,1,2,0|tGingerbread,547a19,2,0,15,,t::-5|b,a5db51,2,3,0|b,96dd28,3,4,0|tIce%20Cream%20Sandwich,293f07,4,0,15,,t::-5|b,83c916,4,5,0|B,6fad0c,5,6,0&chg=7,25&chdl=Eclair|Froyo|Gingerbread|Honeycomb|Ice%20Cream%20Sandwich|Jelly%20Bean&chco=add274,9dd14f,8ece2a,7ab61c,659b11,507d08"
/>
-<p><em>Last historical dataset collected during a 14-day period ending on December 1, 2012</em></p>
+<p><em>Last historical dataset collected during a 14-day period ending on January 1, 2013</em></p>
diff --git a/docs/html/design/index.jd b/docs/html/design/index.jd
index b19422b..1e6b40c 100644
--- a/docs/html/design/index.jd
+++ b/docs/html/design/index.jd
@@ -2,37 +2,6 @@
header.hide=1
footer.hide=1
@jd:body
-<style>
-#butterbar-wrapper {
- position:absolute;
- top:0;
- left:0;
- width:100%;
-}
-#butterbar {
- width:940px;
- margin:0 auto;
-}
-#butterbar-message {
- background-color:#f80;
- float:right;
- font-size:12px;
- font-weight:bold;
- padding:0 10px;
- border-radius: 0 0 5px 5px;
-}
-#butterbar-message a {color:#fff !important}
-#butterbar-message a:hover {text-decoration:underline;}
-</style>
-
- <div id="butterbar-wrapper" >
- <div id="butterbar" >
- <div id="butterbar-message">
-<a target="_blank" href="https://docs.google.com/a/google.com/forms/d/17EFbvdm4FYkocc83EcrKhyhP5Y6tbns_eiBSeQ6ojxU/viewform">
- Take the Android Developer Survey</a>
- </div>
- </div>
-</div>
<style>
#landing-graphic-container {
diff --git a/docs/html/develop/index.jd b/docs/html/develop/index.jd
index 70d3f6d..b4faa58 100644
--- a/docs/html/develop/index.jd
+++ b/docs/html/develop/index.jd
@@ -4,37 +4,6 @@
carousel=1
tabbedList=1
@jd:body
-<style>
-#butterbar-wrapper {
- position:absolute;
- top:0;
- left:0;
- width:100%;
-}
-#butterbar {
- width:940px;
- margin:0 auto;
-}
-#butterbar-message {
- background-color:#f80;
- float:right;
- font-size:12px;
- font-weight:bold;
- padding:0 10px;
- border-radius: 0 0 5px 5px;
-}
-#butterbar-message a {color:#fff !important}
-#butterbar-message a:hover {text-decoration:underline;}
-</style>
-
- <div id="butterbar-wrapper" >
- <div id="butterbar" >
- <div id="butterbar-message">
-<a target="_blank" href="https://docs.google.com/a/google.com/forms/d/17EFbvdm4FYkocc83EcrKhyhP5Y6tbns_eiBSeQ6ojxU/viewform">
- Take the Android Developer Survey</a>
- </div>
- </div>
-</div>
<style>
#noplayer-message {
@@ -152,26 +121,26 @@
<div class="feed-frame">
<!-- DEVELOPER NEWS -->
<ul>
- <li><a href="http://android-developers.blogspot.com/2012/10/google-play-seller-support-in-india.html">
- <div class="feed-image" style="background:url('http://4.bp.blogspot.com/-ekT-9XQi0YY/UH7WT2XjSdI/AAAAAAAABwc/fI5QaPi7QEk/s320/india-apps1.png') no-repeat 0 0"></div>
- <h4>Google Play Seller Support in India</h4>
- <p>Developers in India can sell paid applications, in-app products, and subscriptions in Google Play, with monthly payouts to their local bank accounts...</p>
+ <li><a href="http://android-developers.blogspot.com/2012/12/localize-your-promotional-graphics-on.html">
+ <div class="feed-image" style="background:url('{@docRoot}images/home/play_logo.png') no-repeat 0 0"></div>
+ <h4>Localized Promo Graphics on Google Play</h4>
+ <p>Google Play now lets you provide different promotional graphics, screenshots, and videos for each language you support...</p>
</a></li>
- <li><a href="http://android-developers.blogspot.com/2012/09/google-play-services-and-oauth-identity.html">
- <div class="feed-image" style="background:url('https://lh4.ggpht.com/7z4NItEg-X21zvFGAarKonk-VaysBYthJ30u1JjaQ0-5fjyHNawnmoNeG--4FCACog=w124') no-repeat 0 0"></div>
+ <li><a href="//android-developers.blogspot.com/2012/12/in-app-billing-version-3.html">
+ <div class="feed-image" style="background:url('{@docRoot}images/iab-thumb.png') no-repeat 0 0;background-position:center right;"></div>
+ <h4>In-app Billing Version 3 Now Available</h4>
+ <p>A new version of In-app Billing is available that lets you sell digital goods in your app with just a few lines of code...</p>
+ </a></li>
+ <li><a href="//android-developers.blogspot.com/2012/11/designing-for-tablets-were-here-to-help.html">
+ <div class="feed-image" style="background:url('{@docRoot}design/media/multipane_expand.png') no-repeat 0 0; background-position:right top;"></div>
+ <h4>Designing for Tablets?</h4>
+ <p>Essential resources for everyone in the app development pipeline—from product managers, to designers, to developers, and QA engineers...</p>
+ </a></li>
+ <li><a href="//developer.android.com/google/play-services/index.html">
+ <div class="feed-image" style="background:url('//lh4.ggpht.com/7z4NItEg-X21zvFGAarKonk-VaysBYthJ30u1JjaQ0-5fjyHNawnmoNeG--4FCACog=w124') no-repeat 0 0"></div>
<h4>Google Play services and OAuth Tools</h4>
<p>The rollout of Google Play services to all Android 2.2+ devices worldwide is now complete, and all of those devices now have new tools for working with OAuth 2.0 tokens...</p>
</a></li>
- <li><a href="http://android-developers.blogspot.com/2012/08/creating-your-own-spelling-checker.html">
- <div class="feed-image" style="background:url('http://2.bp.blogspot.com/-QKlztEdM1aA/UC1bH6Kv4UI/AAAAAAAAADo/fQS8-EfBYIQ/s320/spell-check-framed-new.png') no-repeat 0 0"></div>
- <h4>Creating A Spelling Checker Service</h4>
- <p>If you are an IME developer, the Spelling Checker framework gives you a great way to provide an even better experience for your users...</p>
- </a></li>
- <li><a href="http://android-developers.blogspot.com/2012/04/accessibility-are-you-serving-all-your.html">
- <div class="feed-image"></div>
- <h4>Accessibility</h4>
- <p>We recently published some new resources to help developers make their Android applications more accessible... </p>
- </a></li>
</ul>
<!-- FEATURED DOCS -->
<ul>
diff --git a/docs/html/distribute/googleplay/about/distribution.jd b/docs/html/distribute/googleplay/about/distribution.jd
index aff5dab..982bb1f 100644
--- a/docs/html/distribute/googleplay/about/distribution.jd
+++ b/docs/html/distribute/googleplay/about/distribution.jd
@@ -24,7 +24,7 @@
automatic updates of your app, so that your updates are delivered and installed
as soon as you publish them.</p>
-<h2>Reaching the customers you want</h2>
+<h2 id="targeting">Reaching the customers you want</h2>
<p>Google Play does more than connect your app with users—it helps you
reach the broadest possible distribution across the Android ecosystem, while
@@ -45,7 +45,12 @@
<p>When users visit the store, Google Play makes sure that they are in one of
your targeted countries before downloading your app. You can change your country
and carrier targeting at any time just by saving changes in the Google Play
-Android Developer Console</p>
+Android Developer Console.</p>
+
+<p>To help you market to users around the world, you
+can <a href="{@docRoot}distribute/googleplay/publish/preparing.html#localize">localize
+your store listing</a>, including app details and description,
+promotional graphics, screenshots, and more.</p>
<div style="float:right;margin-left:18px;border:1px solid #DDD;margin:1.5em;">
<img src="{@docRoot}images/gp-supported-dev-requirements.png"
diff --git a/docs/html/distribute/googleplay/publish/preparing.jd b/docs/html/distribute/googleplay/publish/preparing.jd
index 9b623e3..097f163 100644
--- a/docs/html/distribute/googleplay/publish/preparing.jd
+++ b/docs/html/distribute/googleplay/publish/preparing.jd
@@ -347,11 +347,12 @@
needs and start the work of localizing well in advance of your target
launch date.</p>
-<p>There are at least two aspects of localization to consider:</p>
+<p>There are at least three aspects of localization to consider:</p>
<ul>
<li>Localizing the strings, images, and other resources in your app</li>
-<li>Localizing you app's store listing details on Google Play</li>
+<li>Localizing your app's store listing details on Google Play</li>
+<li>Localizing the app's graphic assets, screenshots, and videos that accompany your store listing.</li>
</ul>
<p>To get started localizing your app, work with your development team to extract
@@ -361,7 +362,18 @@
<p>To localize your store listing, first create and finalize your app title, description,
and promotional text. Collect and send all of these for localization. You can optionally
-translate the "Recent Changes" text for app updates as well.</p>
+translate the "Recent Changes" text for app updates as well. Later you can add your localized
+listing details in the Developer Console, or you can choose to let Google Play auto-translate
+your listing details into the languages you support.</p>
+
+<p>A key part of making your app listing attractive to a global customer base is
+creating localized versions of your promotional graphics, screenshots and
+videos. For example, your app's feature graphic might include text that should
+be translated, for maximum effectiveness. You can create different versions of
+your promotional graphics for each language and upload them to the Developer
+Console. If you offer a promotional video, you can create localized versions of
+it and then add a link to the correct localized video for each language you
+support.</p>
<p>When your translations are complete, move them into your app resources as needed and test
that they are loaded properly. Save your app's translated listing details for later,
@@ -377,7 +389,7 @@
</tr>
</table>
-<h2 id="graphics">12. Prepare promotional graphics</h2>
+<h2 id="graphics">12. Prepare promotional graphics, screenshots, and videos</h2>
<p>When you publish on Google Play, you can supply a variety of high-quality
graphic assets to showcase your app or brand. After you publish, these appear on
@@ -385,8 +397,16 @@
These graphic assets are key parts of a successful product details page that
attracts and engages users, so you should consider having a professional produce
them for you. Screen shots and videos are also very important, because they show
-what your app looks like, how it's used or played, and what makes it different.
+what your app looks like, how it's used or played, and what makes it different.</p>
+<div class="sidebox-wrapper">
+<div class="sidebox">
+<h3>Localize your promotional graphics and videos<span class="new"> new!</span></h3>
+<p>Google Play now lets you provide different promotional graphics for each
+language you support. Localizing your graphics helps you reach your global
+user base more effectively and is highly recommended.</p>
+</div>
+</div>
<p>All of your graphic assets should be designed so that they are easy to see
and highlight your app or brand in a colorful, interesting way. The assets
should reference the same logo and icon as users will actually find in the All
@@ -394,8 +414,24 @@
fit in well with the graphic assets of other apps published by you, which will
be also be displayed to users on your product details page. </p>
-<p>Because these assets are so important, you should get started on them well in
-advance of your target publishing date. </p>
+<p>To help you market your app more effectively to a global audience, Google
+Play lets you create localized versions of your promotional graphics,
+screenshots, and videos and upload them to the Developer Console. When a user
+visits your app's store listing, Google Play displays the promotional graphic
+and video that you've provided for the user's language.</p>
+
+<p>To localize your promotional graphics, you can translate any embedded text, use
+different imagery or presentation, or change your marketing approach to best address the needs
+of users in specific languages. For example, if your feature or promotional graphic
+includes and embedded product name or tag line, you can translate that text
+and add it to a localized version of the promotional graphic.</p>
+
+<p>Because your localized graphic assets and videos are so important, you should get
+started on creating them and localizing them as needed, well in advance of your target
+publishing date. </p>
+
+<p class="note"><strong>Note:</strong> Localized promotional graphics and videos are supported
+in the Developer Console Preview only.</p>
<table>
<tr>
@@ -403,6 +439,8 @@
<ul style="margin-top:-.5em;">
<li><strong><a href="http://support.google.com/googleplay/android-developer/bin/answer.py?hl=en&answer=1078870">Graphic Assets for your Application
</a></strong> — Details about the graphic assets you need to upload before publishing.</li>
+<li><strong><a href="http://android-developers.blogspot.com/b/post-preview?token=hbE_njsBAAA.dLFzPbe-VFYCS6R3xP16HQ.Z4XO2iUmCqyYpoFPQ4OhiQ&postId=687446965502713273&type=POST">Google Play Featured Image Guidelines
+</a></strong> — Blog post that highlights key design considerations for your app's featured image.</li>
</ul>
</td>
</tr>
@@ -464,6 +502,10 @@
page, make sure that you can enter or upload it to the Developer Console, until
the page is complete and ready for publishing. </p>
+<p>After you've set your app's geographic targeting in the Developer Console,
+remember to add your localized product details, promotional graphics, and so on, for all of the
+languages that you support.</p>
+
<p>If your app is targeting tablet devices, make sure to include at least one screen
shot of the app running on a tablet, and highlight your app's support for tablets
in the app description, release notes, promotional campaigns, and elsewhere.</p>
diff --git a/docs/html/distribute/index.jd b/docs/html/distribute/index.jd
index a950971..54f9301 100644
--- a/docs/html/distribute/index.jd
+++ b/docs/html/distribute/index.jd
@@ -2,53 +2,21 @@
header.hide=1
@jd:body
-<style>
-#butterbar-wrapper {
- position:absolute;
- top:0;
- left:0;
- width:100%;
-}
-#butterbar {
- width:940px;
- margin:0 auto;
-}
-#butterbar-message {
- background-color:#f80;
- float:right;
- font-size:12px;
- font-weight:bold;
- padding:0 10px;
- border-radius: 0 0 5px 5px;
-}
-#butterbar-message a {color:#fff !important}
-#butterbar-message a:hover {text-decoration:underline;}
-</style>
-
- <div id="butterbar-wrapper" >
- <div id="butterbar" >
- <div id="butterbar-message">
-<a target="_blank" href="https://docs.google.com/a/google.com/forms/d/17EFbvdm4FYkocc83EcrKhyhP5Y6tbns_eiBSeQ6ojxU/viewform">
- Take the Android Developer Survey</a>
- </div>
- </div>
-</div>
- <div class="marquee">
-
- <div continer>
-
+<div class="marquee">
<div class="madin-img" style="position:absolute;margin-left:42px;margin-top:76px;">
- <img src="/images/home/google-play.png">
+ <img src="{@docRoot}images/home/google-play.png">
</div>
<div class="copy" style="position:relative;left:480px;width:360;">
<h1 style="margin-bottom:10px;">Your Apps on Google Play</h1>
- <p>The most visited store in the world for Android apps. Cloud-connected and always synced, it's never been easier for users to find and download your apps.</p>
-
- <p><a class="button" href="https://play.google.com/apps/publish/">Go to Developer Console »</a></p>
- </div> </div>
+ <p>The most visited store in the world for Android apps. Cloud-connected and always synced,
+ it's never been easierfor users to find and download your apps.</p>
+ <p><a class="button" href="https://play.google.com/apps/publish/"
+ >Go to Developer Console »</a></p>
+ </div>
</div>
+
<div class="distribute-features col-13" style="clear:both;margin-top:246px;">
<ul>
<li><h5>Growth Engine</h5>
diff --git a/docs/html/google/google_toc.cs b/docs/html/google/google_toc.cs
index 4755390..8b09fe6 100644
--- a/docs/html/google/google_toc.cs
+++ b/docs/html/google/google_toc.cs
@@ -29,7 +29,7 @@
</li>
<li><a href="<?cs var:toroot?>google/play-services/auth.html">
- <span class="en">Authentication</span></a>
+ <span class="en">Authorization</span></a>
</li>
<li><a href="<?cs var:toroot?>google/play-services/plus.html">
diff --git a/docs/html/google/play-services/auth.jd b/docs/html/google/play-services/auth.jd
index b1b19e9..3f46c3f 100644
--- a/docs/html/google/play-services/auth.jd
+++ b/docs/html/google/play-services/auth.jd
@@ -1,4 +1,4 @@
-page.title=Authentication
+page.title=Authorization
@jd:body
<div id="qv-wrapper">
@@ -6,28 +6,28 @@
<h2>In this document</h2>
<ol>
<li><a href="#choose">Choosing an Account</a></li>
- <li><a href="#obtain">Obtaining an Authorization Token</a></li>
+ <li><a href="#obtain">Obtaining an Access Token</a></li>
<li><a href="#handle">Handling Exceptions</a></li>
- <li><a href="#use">Using the Token</a></li>
+ <li><a href="#use">Using the Access Token</a></li>
</ol>
</div>
</div>
<p>
- Google Play services offers a standard authentication flow for all Google APIs and
- all components of Google Play services. In addition, you can leverage the authentication
- portion of the Google Play services SDK to authenticate to services that are not yet supported
- in the Google Play services platform by using the authentication token to manually make API
+ Google Play services offers a standard authorization flow for all Google APIs and
+ all components of Google Play services. In addition, you can leverage the authorization
+ portion of the Google Play services SDK to gain authorization to services that are not yet supported
+ in the Google Play services platform by using the access token to manually make API
requests or using a client library provided by the service provider.
</p>
-<p>For implementation details, see the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code>, which shows you how
-to carry out these basic steps for obtaining an authentication token.</p>
+<p>For implementation details, see the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code>,
+which shows you how to carry out these basic steps for obtaining an acesss token.</p>
<h2 id="choose">Choosing an Account</h2>
<p>
Google Play services leverage existing accounts on an Android-powered device
- to authenticate to the services that you want to use. To obtain an authorization token,
+ to gain authorization to the services that you want to use. To obtain an access token,
a valid Google account is required and it must exist on the device. You can ask your users which
account they want to use by enumerating the Google accounts on the device or using the
built-in
@@ -39,7 +39,7 @@
</p>
<p>
For example, here's how to gather all of the Google accounts on a device and return them
- in an array. When obtaining an authorization token, only the email address of the account is
+ in an array. When obtaining an access token, only the email address of the account is
needed, so that is what the array stores:
</p>
@@ -55,24 +55,24 @@
return names;
}
</pre>
-<h2 id="obtain">Obtaining an Authorization Token</h2>
+<h2 id="obtain">Obtaining an Access Token</h2>
<p>
- With an email address, you can now obtain an authorization token. There are two general
+ With an email address, you can now obtain an access token. There are two general
ways to get a token:</p>
<ul>
<li>Call one of the two overloaded <a
href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
>{@code GoogleAuthUtil.getToken()}</a> methods in a foreground activity where you can
- display a dialog to the user to interactively handle authentication errors.</li>
+ display a dialog to the user to interactively handle authorization errors.</li>
<li>Call one of the three <a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
>{@code getTokenWithNotification()}</a>
- methods if you are authenticating in a background service or sync adapter so that a notification is displayed if an authentication
- error occurs.</a></li>
+ methods if you are trying to gain authorization in a background service or sync adapter so that a
+ notification is displayed if an error occurs.</a></li>
</ul>
<h3>Using getToken()</h3>
- The following code snippet obtains an authentication token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}:
+ The following code snippet obtains an access token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}:
<pre>
HelloActivity mActivity;
String mEmail;
@@ -90,13 +90,13 @@
<p>Call this method off of the main UI thread since it executes network transactions. An easy way to do this
is in an {@link android.os.AsyncTask}.
The sample in the Google Play services SDK shows you how to wrap this call in an AsyncTask.
- If authentication is successful, the token is returned. If not, the exceptions described in
+ If authorization is successful, the token is returned. If not, the exceptions described in
<a href="#handle">Handling Exceptions</a>
are thrown that you can catch and handle appropriately.
</p>
<h3>Using getTokenWithNotification()</h3>
- <p>If you are obtaining authentication tokens in a background service or sync adapter, there
+ <p>If you are obtaining access tokens in a background service or sync adapter, there
are three overloaded
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
>{@code getTokenWithNotification()}</a> methods
@@ -104,11 +104,11 @@
<ul>
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras)}</a>:
- For background services. Displays a notification to the user when authentication errors occur.</li>
+ For background services. Displays a notification to the user when authorization errors occur.</li>
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, android.content.Intent)"
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, Intent callback)}</a>:
This method is for use in background services. It displays a notification to the user
- when authentication errors occur. If a user clicks the notification and then authorizes the
+ when authorization errors occur. If a user clicks the notification and then authorizes the
app to access the account, the intent is broadcasted. When using this method:
<ul>
<li>Create a {@link android.content.BroadcastReceiver} that registers the intent and handles
@@ -123,7 +123,7 @@
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, java.lang.String, android.os.Bundle)"
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, String authority, Bundle syncBundle)}</a>:
This method is for use in sync adapters. It displays a notification to the user when
-authentication errors occur. If a user clicks the notification and then authorizes the
+errors occur. If a user clicks the notification and then authorizes the
app to access the account, the sync adapter retries syncing with the information
contained in the <code>syncBundle</code> parameter.</li>
</ul>
@@ -135,7 +135,7 @@
<h2 id="handle">Handling Exceptions</h2>
<p>
- When requesting an authentication token with
+ When requesting an access token with
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
>{@code GoogleAuthUtil.getToken()}</a>,
the following exceptions can be thrown:
@@ -167,7 +167,7 @@
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code
GoogleAuthException}</a>:
This exception is thrown when the authorization fails, such as when an invalid scope is
- specified or if the email address used to authenticate is actually not on the user's
+ specified or if the email address used for authorization is actually not on the user's
device.
</li>
<li>
@@ -189,7 +189,7 @@
-<h2 id="use">Using the Token</h2>
+<h2 id="use">Using the Access Token</h2>
<p>
Once you have successfully obtained a token, you can use it to access Google services.
Many Google services provide client libraries, so it is recommended that you use these when
@@ -224,7 +224,7 @@
<p>
Notice that you must manually invalidate the token if the response from the server
- signifies an authentication error (401). This could mean the authentication token
+ signifies an authorization error (401). This could mean the access token
being used is invalid for the service's scope or the token may have expired. If this is the
case, obtain a new token using <a
href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
diff --git a/docs/html/google/play-services/dist.jd b/docs/html/google/play-services/dist.jd
deleted file mode 100644
index e179bff..0000000
--- a/docs/html/google/play-services/dist.jd
+++ /dev/null
@@ -1,56 +0,0 @@
-page.title=Google Play Distribution and Licensing
-@jd:body
-
-
-<h2 id="distribution">
- Manage App Distribution and Licensing
-</h2>
-<p>
- Google Play allows you to manage your app distribution with features that let you control which users
- can download your app as well as deliver separate versions of your app based on certain
- characteristics like platform version.
-</p>
-<div class="vspace size-1">
-
-</div>
-<div class="layout-content-row">
- <div class="layout-content-col span-6">
- <h4>
- Device Filtering
- </h4>
- <p>
- Make sure your app gets to the right users by filtering on a wide range of characteristics
- such as platform versions and hardware features.
- </p><p><a href="{@docRoot}google/play/filters.html">Learn more »</a></p>
- </div>
-
- <div class="layout-content-col span-6">
- <h4>
- Multiple APK Support
- </h4>
- <p>
- Distribute different APKs based on a variety of properties such as platform version, screen
- size, and GLES texture compression support.
- </p><p><a href="{@docRoot}google/play/publishing/multiple-apks.html">Learn more »</a></p>
- </div>
-
-<div class="layout-content-row">
- <div class="layout-content-col span-6">
- <h4>
- APK Expansion files
- </h4>
- <p>
- Tap into Google's content delivery services by serving up to 4GB of assets for free. Provide
- users with high-fidelity graphics, media files, or other large assets that are required by
- your app.
- </p><a href="{@docRoot}google/play/expansion-files.html">Learn more »</a>
- </div>
-
- <div class="layout-content-col span-6">
- <h4>
- Application Licensing
- </h4>
- <p>Protect your revenue streams and integrate policies for usage into your app.
- </p><a href="{@docRoot}google/play/licensing/index.html">Learn more »</a>
- </div>
-</div>
\ No newline at end of file
diff --git a/docs/html/google/play-services/index.jd b/docs/html/google/play-services/index.jd
index fae1e1a..82167bc 100644
--- a/docs/html/google/play-services/index.jd
+++ b/docs/html/google/play-services/index.jd
@@ -37,10 +37,10 @@
</div>
<div class="layout-content-col span-4">
-<h4>Standard Authentication</h4>
-<p>All products in Google Play services share a common authentication API
+<h4>Standard Authorization</h4>
+<p>All products in Google Play services share a common authorization API
that leverages the existing Google accounts on the device. You and your
- users have a consistent and safe way to grant and receive OAuth2 authentication
+ users have a consistent and safe way to grant and receive OAuth2 access tokens
to Google services.</p>
</div>
@@ -66,7 +66,7 @@
<h4 id="client-lib">The Google Play services client library</h4>
<p>
The client library contains the interfaces to the individual Google
- services and allows you to obtain authorization from users to authenticate
+ services and allows you to obtain authorization from users to gain access
to these services with their credentials. It also contains APIs that allow
you to resolve any issues at runtime, such as a missing, disabled, or out-of-date
Google Play services APK. The client library has a light footprint if you use
@@ -90,7 +90,7 @@
The Google Play services APK contains the individual Google services and runs
as a background service in the Android OS. You interact with the background service
through the client library and the service carries out the actions on your behalf.
- An easy-to-use authentication flow is also
+ An easy-to-use authorization flow is also
provided to gain access to the each Google service, which provides consistency for both
you and your users.
</p>
diff --git a/docs/html/guide/practices/app-design/jni.jd b/docs/html/guide/practices/app-design/jni.jd
deleted file mode 100644
index ddfa0e3..0000000
--- a/docs/html/guide/practices/app-design/jni.jd
+++ /dev/null
@@ -1,719 +0,0 @@
-page.title=JNI Tips
-@jd:body
-
-<div id="qv-wrapper">
-<div id="qv">
-
-<h2>In this document</h2>
-<ol>
- <li><a href="#JavaVM_and_JNIEnv">JavaVM and JNIEnv</a></li>
- <li><a href="#threads">Threads</a></li>
- <li><a href="#jclass_jmethodID_and_jfieldID">jclass, jmethodID, and jfieldID</a></li>
- <li><a href="#local_and_global_references">Local and Global References</a></li>
- <li><a href="#UTF_8_and_UTF_16_strings">UTF-8 and UTF-16 Strings</a></li>
- <li><a href="#arrays">Primitive Arrays</a></li>
- <li><a href="#region_calls">Region Calls</a></li>
- <li><a href="#exceptions">Exceptions</a></li>
- <li><a href="#extended_checking">Extended Checking</a> </li>
- <li><a href="#native_libraries">Native Libraries</a></li>
- <li><a href="#64_bit">64-bit Considerations</a></li>
- <li><a href="#unsupported">Unsupported Features/Backwards Compatibility</a></li>
- <li><a href="#faq_ULE">FAQ: Why do I get <code>UnsatisfiedLinkError</code></a></li>
- <li><a href="#faq_FindClass">FAQ: Why didn't <code>FindClass</code> find my class?</a></li>
- <li><a href="#faq_sharing">FAQ: How do I share raw data with native code?</a></li>
-</ol>
-
-</div>
-</div>
-
-<p>JNI is the Java Native Interface. It defines a way for managed code
-(written in the Java programming language) to interact with native
-code (written in C/C++). It's vendor-neutral, has support for loading code from
-dynamic shared libraries, and while cumbersome at times is reasonably efficient.</p>
-
-<p>You really should read through the
-<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 6</a>
-to get a sense for how JNI works and what features are available. Some
-aspects of the interface aren't immediately obvious on
-first reading, so you may find the next few sections handy.
-There's a more detailed <a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">JNI Programmer's Guide and Specification</a>.</p>
-
-
-<a name="JavaVM_and_JNIEnv" id="JavaVM_and_JNIEnv"></a>
-<h2>JavaVM and JNIEnv</h2>
-
-<p>JNI defines two key data structures, "JavaVM" and "JNIEnv". Both of these are essentially
-pointers to pointers to function tables. (In the C++ version, they're classes with a
-pointer to a function table and a member function for each JNI function that indirects through
-the table.) The JavaVM provides the "invocation interface" functions,
-which allow you to create and destroy a JavaVM. In theory you can have multiple JavaVMs per process,
-but Android only allows one.</p>
-
-<p>The JNIEnv provides most of the JNI functions. Your native functions all receive a JNIEnv as
-the first argument.</p>
-
-<p>The JNIEnv is used for thread-local storage. For this reason, <strong>you cannot share a JNIEnv between threads</strong>.
-If a piece of code has no other way to get its JNIEnv, you should share
-the JavaVM, and use <code>GetEnv</code> to discover the thread's JNIEnv. (Assuming it has one; see <code>AttachCurrentThread</code> below.)</p>
-
-<p>The C declarations of JNIEnv and JavaVM are different from the C++
-declarations. The <code>"jni.h"</code> include file provides different typedefs
-depending on whether it's included into C or C++. For this reason it's a bad idea to
-include JNIEnv arguments in header files included by both languages. (Put another way: if your
-header file requires <code>#ifdef __cplusplus</code>, you may have to do some extra work if anything in
-that header refers to JNIEnv.)</p>
-
-<a name="threads" id="threads"></a>
-<h2>Threads</h2>
-
-<p>All threads are Linux threads, scheduled by the kernel. They're usually
-started from managed code (using <code>Thread.start</code>),
-but they can also be created elsewhere and then attached to the JavaVM. For
-example, a thread started with <code>pthread_create</code> can be attached
-with the JNI <code>AttachCurrentThread</code> or
-<code>AttachCurrentThreadAsDaemon</code> functions. Until a thread is
-attached, it has no JNIEnv, and <strong>cannot make JNI calls</strong>.</p>
-
-<p>Attaching a natively-created thread causes a <code>java.lang.Thread</code>
-object to be constructed and added to the "main" <code>ThreadGroup</code>,
-making it visible to the debugger. Calling <code>AttachCurrentThread</code>
-on an already-attached thread is a no-op.</p>
-
-<p>Android does not suspend threads executing native code. If
-garbage collection is in progress, or the debugger has issued a suspend
-request, Android will pause the thread the next time it makes a JNI call.</p>
-
-<p>Threads attached through JNI <strong>must call
-<code>DetachCurrentThread</code> before they exit</strong>.
-If coding this directly is awkward, in Android 2.0 (Eclair) and higher you
-can use <code>pthread_key_create</code> to define a destructor
-function that will be called before the thread exits, and
-call <code>DetachCurrentThread</code> from there. (Use that
-key with <code>pthread_setspecific</code> to store the JNIEnv in
-thread-local-storage; that way it'll be passed into your destructor as
-the argument.)</p>
-
-
-<a name="jclass_jmethodID_and_jfieldID" id="jclass_jmethodID_and_jfieldID"></a>
-<h2>jclass, jmethodID, and jfieldID</h2>
-
-<p>If you want to access an object's field from native code, you would do the following:</p>
-
-<ul>
-<li> Get the class object reference for the class with <code>FindClass</code></li>
-<li> Get the field ID for the field with <code>GetFieldID</code></li>
-<li> Get the contents of the field with something appropriate, such as
-<code>GetIntField</code></li>
-</ul>
-
-<p>Similarly, to call a method, you'd first get a class object reference and then a method ID. The IDs are often just
-pointers to internal runtime data structures. Looking them up may require several string
-comparisons, but once you have them the actual call to get the field or invoke the method
-is very quick.</p>
-
-<p>If performance is important, it's useful to look the values up once and cache the results
-in your native code. Because there is a limit of one JavaVM per process, it's reasonable
-to store this data in a static local structure.</p>
-
-<p>The class references, field IDs, and method IDs are guaranteed valid until the class is unloaded. Classes
-are only unloaded if all classes associated with a ClassLoader can be garbage collected,
-which is rare but will not be impossible in Android. Note however that
-the <code>jclass</code>
-is a class reference and <strong>must be protected</strong> with a call
-to <code>NewGlobalRef</code> (see the next section).</p>
-
-<p>If you would like to cache the IDs when a class is loaded, and automatically re-cache them
-if the class is ever unloaded and reloaded, the correct way to initialize
-the IDs is to add a piece of code that looks like this to the appropriate class:</p>
-
-<pre> /*
- * We use a class initializer to allow the native code to cache some
- * field offsets. This native function looks up and caches interesting
- * class/field/method IDs. Throws on failure.
- */
- private static native void nativeInit();
-
- static {
- nativeInit();
- }</pre>
-
-<p>Create a <code>nativeClassInit</code> method in your C/C++ code that performs the ID lookups. The code
-will be executed once, when the class is initialized. If the class is ever unloaded and
-then reloaded, it will be executed again.</p>
-
-<a name="local_and_global_references" id="local_and_global_references"></a>
-<h2>Local and Global References</h2>
-
-<p>Every argument passed to a native method, and almost every object returned
-by a JNI function is a "local reference". This means that it's valid for the
-duration of the current native method in the current thread.
-<strong>Even if the object itself continues to live on after the native method
-returns, the reference is not valid.</strong>
-<p>This applies to all sub-classes of <code>jobject</code>, including
-<code>jclass</code>, <code>jstring</code>, and <code>jarray</code>.
-(The runtime will warn you about most reference mis-uses when extended JNI
-checks are enabled.)</p>
-<p>The only way to get non-local references is via the functions
-<code>NewGlobalRef</code> and <code>NewWeakGlobalRef</code>.
-
-<p>If you want to hold on to a reference for a longer period, you must use
-a "global" reference. The <code>NewGlobalRef</code> function takes the
-local reference as an argument and returns a global one.
-The global reference is guaranteed to be valid until you call
-<code>DeleteGlobalRef</code>.</p>
-
-<p>This pattern is commonly used when caching a jclass returned
-from <code>FindClass</code>, e.g.:</p>
-<pre>jclass localClass = env->FindClass("MyClass");
-jclass globalClass = reinterpret_cast<jclass>(env->NewGlobalRef(localClass));</pre>
-
-<p>All JNI methods accept both local and global references as arguments.
-It's possible for references to the same object to have different values.
-For example, the return values from consecutive calls to
-<code>NewGlobalRef</code> on the same object may be different.
-<strong>To see if two references refer to the same object,
-you must use the <code>IsSameObject</code> function.</strong> Never compare
-references with <code>==</code> in native code.</p>
-
-<p>One consequence of this is that you
-<strong>must not assume object references are constant or unique</strong>
-in native code. The 32-bit value representing an object may be different
-from one invocation of a method to the next, and it's possible that two
-different objects could have the same 32-bit value on consecutive calls. Do
-not use <code>jobject</code> values as keys.</p>
-
-<p>Programmers are required to "not excessively allocate" local references. In practical terms this means
-that if you're creating large numbers of local references, perhaps while running through an array of
-objects, you should free them manually with
-<code>DeleteLocalRef</code> instead of letting JNI do it for you. The
-implementation is only required to reserve slots for
-16 local references, so if you need more than that you should either delete as you go or use
-<code>EnsureLocalCapacity</code>/<code>PushLocalFrame</code> to reserve more.</p>
-
-<p>Note that <code>jfieldID</code>s and <code>jmethodID</code>s are opaque
-types, not object references, and should not be passed to
-<code>NewGlobalRef</code>. The raw data
-pointers returned by functions like <code>GetStringUTFChars</code>
-and <code>GetByteArrayElements</code> are also not objects. (They may be passed
-between threads, and are valid until the matching Release call.)</p>
-
-<p>One unusual case deserves separate mention. If you attach a native
-thread with <code>AttachCurrentThread</code>, the code you are running will
-never automatically free local references until the thread detaches. Any local
-references you create will have to be deleted manually. In general, any native
-code that creates local references in a loop probably needs to do some manual
-deletion.</p>
-
-<a name="UTF_8_and_UTF_16_strings" id="UTF_8_and_UTF_16_strings"></a>
-<h2>UTF-8 and UTF-16 Strings</h2>
-
-<p>The Java programming language uses UTF-16. For convenience, JNI provides methods that work with <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> as well. The
-modified encoding is useful for C code because it encodes \u0000 as 0xc0 0x80 instead of 0x00.
-The nice thing about this is that you can count on having C-style zero-terminated strings,
-suitable for use with standard libc string functions. The down side is that you cannot pass
-arbitrary UTF-8 data to JNI and expect it to work correctly.</p>
-
-<p>If possible, it's usually faster to operate with UTF-16 strings. Android
-currently does not require a copy in <code>GetStringChars</code>, whereas
-<code>GetStringUTFChars</code> requires an allocation and a conversion to
-UTF-8. Note that
-<strong>UTF-16 strings are not zero-terminated</strong>, and \u0000 is allowed,
-so you need to hang on to the string length as well as
-the jchar pointer.</p>
-
-<p><strong>Don't forget to <code>Release</code> the strings you <code>Get</code></strong>. The
-string functions return <code>jchar*</code> or <code>jbyte*</code>, which
-are C-style pointers to primitive data rather than local references. They
-are guaranteed valid until <code>Release</code> is called, which means they are not
-released when the native method returns.</p>
-
-<p><strong>Data passed to NewStringUTF must be in Modified UTF-8 format</strong>. A
-common mistake is reading character data from a file or network stream
-and handing it to <code>NewStringUTF</code> without filtering it.
-Unless you know the data is 7-bit ASCII, you need to strip out high-ASCII
-characters or convert them to proper Modified UTF-8 form. If you don't,
-the UTF-16 conversion will likely not be what you expect. The extended
-JNI checks will scan strings and warn you about invalid data, but they
-won't catch everything.</p>
-
-<a name="arrays" id="arrays"></a>
-<h2>Primitive Arrays</h2>
-
-<p>JNI provides functions for accessing the contents of array objects.
-While arrays of objects must be accessed one entry at a time, arrays of
-primitives can be read and written directly as if they were declared in C.</p>
-
-<p>To make the interface as efficient as possible without constraining
-the VM implementation, the <code>Get<PrimitiveType>ArrayElements</code>
-family of calls allows the runtime to either return a pointer to the actual elements, or
-allocate some memory and make a copy. Either way, the raw pointer returned
-is guaranteed to be valid until the corresponding <code>Release</code> call
-is issued (which implies that, if the data wasn't copied, the array object
-will be pinned down and can't be relocated as part of compacting the heap).
-<strong>You must <code>Release</code> every array you <code>Get</code>.</strong> Also, if the <code>Get</code>
-call fails, you must ensure that your code doesn't try to <code>Release</code> a NULL
-pointer later.</p>
-
-<p>You can determine whether or not the data was copied by passing in a
-non-NULL pointer for the <code>isCopy</code> argument. This is rarely
-useful.</p>
-
-<p>The <code>Release</code> call takes a <code>mode</code> argument that can
-have one of three values. The actions performed by the runtime depend upon
-whether it returned a pointer to the actual data or a copy of it:</p>
-
-<ul>
- <li><code>0</code>
- <ul>
- <li>Actual: the array object is un-pinned.
- <li>Copy: data is copied back. The buffer with the copy is freed.
- </ul>
- <li><code>JNI_COMMIT</code>
- <ul>
- <li>Actual: does nothing.
- <li>Copy: data is copied back. The buffer with the copy
- <strong>is not freed</strong>.
- </ul>
- <li><code>JNI_ABORT</code>
- <ul>
- <li>Actual: the array object is un-pinned. Earlier
- writes are <strong>not</strong> aborted.
- <li>Copy: the buffer with the copy is freed; any changes to it are lost.
- </ul>
-</ul>
-
-<p>One reason for checking the <code>isCopy</code> flag is to know if
-you need to call <code>Release</code> with <code>JNI_COMMIT</code>
-after making changes to an array — if you're alternating between making
-changes and executing code that uses the contents of the array, you may be
-able to
-skip the no-op commit. Another possible reason for checking the flag is for
-efficient handling of <code>JNI_ABORT</code>. For example, you might want
-to get an array, modify it in place, pass pieces to other functions, and
-then discard the changes. If you know that JNI is making a new copy for
-you, there's no need to create another "editable" copy. If JNI is passing
-you the original, then you do need to make your own copy.</p>
-
-<p>It is a common mistake (repeated in example code) to assume that you can skip the <code>Release</code> call if
-<code>*isCopy</code> is false. This is not the case. If no copy buffer was
-allocated, then the original memory must be pinned down and can't be moved by
-the garbage collector.</p>
-
-<p>Also note that the <code>JNI_COMMIT</code> flag does <strong>not</strong> release the array,
-and you will need to call <code>Release</code> again with a different flag
-eventually.</p>
-
-
-<a name="region_calls" id="region_calls"></a>
-<h2>Region Calls</h2>
-
-<p>There is an alternative to calls like <code>Get<Type>ArrayElements</code>
-and <code>GetStringChars</code> that may be very helpful when all you want
-to do is copy data in or out. Consider the following:</p>
-
-<pre> jbyte* data = env->GetByteArrayElements(array, NULL);
- if (data != NULL) {
- memcpy(buffer, data, len);
- env->ReleaseByteArrayElements(array, data, JNI_ABORT);
- }</pre>
-
-<p>This grabs the array, copies the first <code>len</code> byte
-elements out of it, and then releases the array. Depending upon the
-implementation, the <code>Get</code> call will either pin or copy the array
-contents.
-The code copies the data (for perhaps a second time), then calls <code>Release</code>; in this case
-<code>JNI_ABORT</code> ensures there's no chance of a third copy.</p>
-
-<p>One can accomplish the same thing more simply:</p>
-<pre> env->GetByteArrayRegion(array, 0, len, buffer);</pre>
-
-<p>This has several advantages:</p>
-<ul>
- <li>Requires one JNI call instead of 2, reducing overhead.
- <li>Doesn't require pinning or extra data copies.
- <li>Reduces the risk of programmer error — no risk of forgetting
- to call <code>Release</code> after something fails.
-</ul>
-
-<p>Similarly, you can use the <code>Set<Type>ArrayRegion</code> call
-to copy data into an array, and <code>GetStringRegion</code> or
-<code>GetStringUTFRegion</code> to copy characters out of a
-<code>String</code>.
-
-
-<a name="exceptions" id="exceptions"></a>
-<h2>Exceptions</h2>
-
-<p><strong>You must not call most JNI functions while an exception is pending.</strong>
-Your code is expected to notice the exception (via the function's return value,
-<code>ExceptionCheck</code>, or <code>ExceptionOccurred</code>) and return,
-or clear the exception and handle it.</p>
-
-<p>The only JNI functions that you are allowed to call while an exception is
-pending are:</p>
-<ul>
- <li><code>DeleteGlobalRef</code>
- <li><code>DeleteLocalRef</code>
- <li><code>DeleteWeakGlobalRef</code>
- <li><code>ExceptionCheck</code>
- <li><code>ExceptionClear</code>
- <li><code>ExceptionDescribe</code>
- <li><code>ExceptionOccurred</code>
- <li><code>MonitorExit</code>
- <li><code>PopLocalFrame</code>
- <li><code>PushLocalFrame</code>
- <li><code>Release<PrimitiveType>ArrayElements</code>
- <li><code>ReleasePrimitiveArrayCritical</code>
- <li><code>ReleaseStringChars</code>
- <li><code>ReleaseStringCritical</code>
- <li><code>ReleaseStringUTFChars</code>
-</ul>
-
-<p>Many JNI calls can throw an exception, but often provide a simpler way
-of checking for failure. For example, if <code>NewString</code> returns
-a non-NULL value, you don't need to check for an exception. However, if
-you call a method (using a function like <code>CallObjectMethod</code>),
-you must always check for an exception, because the return value is not
-going to be valid if an exception was thrown.</p>
-
-<p>Note that exceptions thrown by interpreted code do not unwind native stack
-frames, and Android does not yet support C++ exceptions.
-The JNI <code>Throw</code> and <code>ThrowNew</code> instructions just
-set an exception pointer in the current thread. Upon returning to managed
-from native code, the exception will be noted and handled appropriately.</p>
-
-<p>Native code can "catch" an exception by calling <code>ExceptionCheck</code> or
-<code>ExceptionOccurred</code>, and clear it with
-<code>ExceptionClear</code>. As usual,
-discarding exceptions without handling them can lead to problems.</p>
-
-<p>There are no built-in functions for manipulating the <code>Throwable</code> object
-itself, so if you want to (say) get the exception string you will need to
-find the <code>Throwable</code> class, look up the method ID for
-<code>getMessage "()Ljava/lang/String;"</code>, invoke it, and if the result
-is non-NULL use <code>GetStringUTFChars</code> to get something you can
-hand to <code>printf(3)</code> or equivalent.</p>
-
-
-<a name="extended_checking" id="extended_checking"></a>
-<h2>Extended Checking</h2>
-
-<p>JNI does very little error checking. Errors usually result in a crash. Android also offers a mode called CheckJNI, where the JavaVM and JNIEnv function table pointers are switched to tables of functions that perform an extended series of checks before calling the standard implementation.</p>
-
-<p>The additional checks include:</p>
-
-<ul>
-<li>Arrays: attempting to allocate a negative-sized array.</li>
-<li>Bad pointers: passing a bad jarray/jclass/jobject/jstring to a JNI call, or passing a NULL pointer to a JNI call with a non-nullable argument.</li>
-<li>Class names: passing anything but the “java/lang/String” style of class name to a JNI call.</li>
-<li>Critical calls: making a JNI call between a “critical” get and its corresponding release.</li>
-<li>Direct ByteBuffers: passing bad arguments to <code>NewDirectByteBuffer</code>.</li>
-<li>Exceptions: making a JNI call while there’s an exception pending.</li>
-<li>JNIEnv*s: using a JNIEnv* from the wrong thread.</li>
-<li>jfieldIDs: using a NULL jfieldID, or using a jfieldID to set a field to a value of the wrong type (trying to assign a StringBuilder to a String field, say), or using a jfieldID for a static field to set an instance field or vice versa, or using a jfieldID from one class with instances of another class.</li>
-<li>jmethodIDs: using the wrong kind of jmethodID when making a <code>Call*Method</code> JNI call: incorrect return type, static/non-static mismatch, wrong type for ‘this’ (for non-static calls) or wrong class (for static calls).</li>
-<li>References: using <code>DeleteGlobalRef</code>/<code>DeleteLocalRef</code> on the wrong kind of reference.</li>
-<li>Release modes: passing a bad release mode to a release call (something other than <code>0</code>, <code>JNI_ABORT</code>, or <code>JNI_COMMIT</code>).</li>
-<li>Type safety: returning an incompatible type from your native method (returning a StringBuilder from a method declared to return a String, say).</li>
-<li>UTF-8: passing an invalid <a href="http://en.wikipedia.org/wiki/UTF-8#Modified_UTF-8">Modified UTF-8</a> byte sequence to a JNI call.</li>
-</ul>
-
-<p>(Accessibility of methods and fields is still not checked: access restrictions don't apply to native code.)</p>
-
-<p>There are several ways to enable CheckJNI.</p>
-
-<p>If you’re using the emulator, CheckJNI is on by default.</p>
-
-<p>If you have a rooted device, you can use the following sequence of commands to restart the runtime with CheckJNI enabled:</p>
-
-<pre>adb shell stop
-adb shell setprop dalvik.vm.checkjni true
-adb shell start</pre>
-
-<p>In either of these cases, you’ll see something like this in your logcat output when the runtime starts:</p>
-
-<pre>D AndroidRuntime: CheckJNI is ON</pre>
-
-<p>If you have a regular device, you can use the following command:</p>
-
-<pre>adb shell setprop debug.checkjni 1</pre>
-
-<p>This won’t affect already-running apps, but any app launched from that point on will have CheckJNI enabled. (Change the property to any other value or simply rebooting will disable CheckJNI again.) In this case, you’ll see something like this in your logcat output the next time an app starts:</p>
-
-<pre>D Late-enabling CheckJNI</pre>
-
-
-
-
-<a name="native_libraries" id="native_libraries"></a>
-<h2>Native Libraries</h2>
-
-<p>You can load native code from shared libraries with the standard
-<code>System.loadLibrary</code> call. The
-preferred way to get at your native code is:</p>
-
-<ul>
-<li> Call <code>System.loadLibrary</code> from a static class
-initializer. (See the earlier example, where one is used to call
-<code>nativeClassInit</code>.) The argument is the "undecorated"
-library name, so to load "libfubar.so" you would pass in "fubar".</li>
-<li> Provide a native function: <code><strong>jint JNI_OnLoad(JavaVM* vm, void* reserved)</strong></code></li>
-<li>In <code>JNI_OnLoad</code>, register all of your native methods. You
-should declare
-the methods "static" so the names don't take up space in the symbol table
-on the device.</li>
-</ul>
-
-<p>The <code>JNI_OnLoad</code> function should look something like this if
-written in C++:</p>
-<pre>jint JNI_OnLoad(JavaVM* vm, void* reserved)
-{
- JNIEnv* env;
- if (vm->GetEnv(reinterpret_cast<void**>(&env), JNI_VERSION_1_6) != JNI_OK) {
- return -1;
- }
-
- // Get jclass with env->FindClass.
- // Register methods with env->RegisterNatives.
-
- return JNI_VERSION_1_6;
-}</pre>
-
-<p>You can also call <code>System.load</code> with the full path name of the
-shared library. For Android apps, you may find it useful to get the full
-path to the application's private data storage area from the context object.</p>
-
-<p>This is the recommended approach, but not the only approach. Explicit
-registration is not required, nor is it necessary that you provide a
-<code>JNI_OnLoad</code> function.
-You can instead use "discovery" of native methods that are named in a
-specific way (see <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp615">the JNI spec</a> for details), though this is less desirable because if a method signature is wrong you won't know
-about it until the first time the method is actually used.</p>
-
-<p>One other note about <code>JNI_OnLoad</code>: any <code>FindClass</code>
-calls you make from there will happen in the context of the class loader
-that was used to load the shared library. Normally <code>FindClass</code>
-uses the loader associated with the method at the top of the interpreted
-stack, or if there isn't one (because the thread was just attached) it uses
-the "system" class loader. This makes
-<code>JNI_OnLoad</code> a convenient place to look up and cache class
-object references.</p>
-
-
-<a name="64_bit" id="64_bit"></a>
-<h2>64-bit Considerations</h2>
-
-<p>Android is currently expected to run on 32-bit platforms. In theory it
-could be built for a 64-bit system, but that is not a goal at this time.
-For the most part this isn't something that you will need to worry about
-when interacting with native code,
-but it becomes significant if you plan to store pointers to native
-structures in integer fields in an object. To support architectures
-that use 64-bit pointers, <strong>you need to stash your native pointers in a
-<code>long</code> field rather than an <code>int</code></strong>.
-
-
-<a name="unsupported" id="unsupported"></a>
-<h2>Unsupported Features/Backwards Compatibility</h2>
-
-<p>All JNI 1.6 features are supported, with the following exception:</p>
-<ul>
- <li><code>DefineClass</code> is not implemented. Android does not use
- Java bytecodes or class files, so passing in binary class data
- doesn't work.</li>
-</ul>
-
-<p>For backward compatibility with older Android releases, you may need to
-be aware of:</p>
-<ul>
- <li><b>Dynamic lookup of native functions</b>
- <p>Until Android 2.0 (Eclair), the '$' character was not properly
- converted to "_00024" during searches for method names. Working
- around this requires using explicit registration or moving the
- native methods out of inner classes.
- <li><b>Detaching threads</b>
- <p>Until Android 2.0 (Eclair), it was not possible to use a <code>pthread_key_create</code>
- destructor function to avoid the "thread must be detached before
- exit" check. (The runtime also uses a pthread key destructor function,
- so it'd be a race to see which gets called first.)
- <li><b>Weak global references</b>
- <p>Until Android 2.2 (Froyo), weak global references were not implemented.
- Older versions will vigorously reject attempts to use them. You can use
- the Android platform version constants to test for support.
- <p>Until Android 4.0 (Ice Cream Sandwich), weak global references could only
- be passed to <code>NewLocalRef</code>, <code>NewGlobalRef</code>, and
- <code>DeleteWeakGlobalRef</code>. (The spec strongly encourages
- programmers to create hard references to weak globals before doing
- anything with them, so this should not be at all limiting.)
- <p>From Android 4.0 (Ice Cream Sandwich) on, weak global references can be
- used like any other JNI references.</li>
- <li><b>Local references</b>
- <p>Until Android 4.0 (Ice Cream Sandwich), local references were
- actually direct pointers. Ice Cream Sandwich added the indirection
- necessary to support better garbage collectors, but this means that lots
- of JNI bugs are undetectable on older releases. See
- <a href="http://android-developers.blogspot.com/2011/11/jni-local-reference-changes-in-ics.html">JNI Local Reference Changes in ICS</a> for more details.
- <li><b>Determining reference type with <code>GetObjectRefType</code></b>
- <p>Until Android 4.0 (Ice Cream Sandwich), as a consequence of the use of
- direct pointers (see above), it was impossible to implement
- <code>GetObjectRefType</code> correctly. Instead we used a heuristic
- that looked through the weak globals table, the arguments, the locals
- table, and the globals table in that order. The first time it found your
- direct pointer, it would report that your reference was of the type it
- happened to be examining. This meant, for example, that if
- you called <code>GetObjectRefType</code> on a global jclass that happened
- to be the same as the jclass passed as an implicit argument to your static
- native method, you'd get <code>JNILocalRefType</code> rather than
- <code>JNIGlobalRefType</code>.
-</ul>
-
-
-<a name="faq_ULE" id="faq_ULE"></a>
-<h2>FAQ: Why do I get <code>UnsatisfiedLinkError</code>?</h2>
-
-<p>When working on native code it's not uncommon to see a failure like this:</p>
-<pre>java.lang.UnsatisfiedLinkError: Library foo not found</pre>
-
-<p>In some cases it means what it says — the library wasn't found. In
-other cases the library exists but couldn't be opened by <code>dlopen(3)</code>, and
-the details of the failure can be found in the exception's detail message.</p>
-
-<p>Common reasons why you might encounter "library not found" exceptions:</p>
-<ul>
- <li>The library doesn't exist or isn't accessible to the app. Use
- <code>adb shell ls -l <path></code> to check its presence
- and permissions.
- <li>The library wasn't built with the NDK. This can result in
- dependencies on functions or libraries that don't exist on the device.
-</ul>
-
-<p>Another class of <code>UnsatisfiedLinkError</code> failures looks like:</p>
-<pre>java.lang.UnsatisfiedLinkError: myfunc
- at Foo.myfunc(Native Method)
- at Foo.main(Foo.java:10)</pre>
-
-<p>In logcat, you'll see:</p>
-<pre>W/dalvikvm( 880): No implementation found for native LFoo;.myfunc ()V</pre>
-
-<p>This means that the runtime tried to find a matching method but was
-unsuccessful. Some common reasons for this are:</p>
-<ul>
- <li>The library isn't getting loaded. Check the logcat output for
- messages about library loading.
- <li>The method isn't being found due to a name or signature mismatch. This
- is commonly caused by:
- <ul>
- <li>For lazy method lookup, failing to declare C++ functions
- with <code>extern "C"</code> and appropriate
- visibility (<code>JNIEXPORT</code>). Note that prior to Ice Cream
- Sandwich, the JNIEXPORT macro was incorrect, so using a new GCC with
- an old <code>jni.h</code> won't work.
- You can use <code>arm-eabi-nm</code>
- to see the symbols as they appear in the library; if they look
- mangled (something like <code>_Z15Java_Foo_myfuncP7_JNIEnvP7_jclass</code>
- rather than <code>Java_Foo_myfunc</code>), or if the symbol type is
- a lowercase 't' rather than an uppercase 'T', then you need to
- adjust the declaration.
- <li>For explicit registration, minor errors when entering the
- method signature. Make sure that what you're passing to the
- registration call matches the signature in the log file.
- Remember that 'B' is <code>byte</code> and 'Z' is <code>boolean</code>.
- Class name components in signatures start with 'L', end with ';',
- use '/' to separate package/class names, and use '$' to separate
- inner-class names (<code>Ljava/util/Map$Entry;</code>, say).
- </ul>
-</ul>
-
-<p>Using <code>javah</code> to automatically generate JNI headers may help
-avoid some problems.
-
-
-<a name="faq_FindClass" id="faq_FindClass"></a>
-<h2>FAQ: Why didn't <code>FindClass</code> find my class?</h2>
-
-<p>Make sure that the class name string has the correct format. JNI class
-names start with the package name and are separated with slashes,
-such as <code>java/lang/String</code>. If you're looking up an array class,
-you need to start with the appropriate number of square brackets and
-must also wrap the class with 'L' and ';', so a one-dimensional array of
-<code>String</code> would be <code>[Ljava/lang/String;</code>.</p>
-
-<p>If the class name looks right, you could be running into a class loader
-issue. <code>FindClass</code> wants to start the class search in the
-class loader associated with your code. It examines the call stack,
-which will look something like:
-<pre> Foo.myfunc(Native Method)
- Foo.main(Foo.java:10)
- dalvik.system.NativeStart.main(Native Method)</pre>
-
-<p>The topmost method is <code>Foo.myfunc</code>. <code>FindClass</code>
-finds the <code>ClassLoader</code> object associated with the <code>Foo</code>
-class and uses that.</p>
-
-<p>This usually does what you want. You can get into trouble if you
-create a thread yourself (perhaps by calling <code>pthread_create</code>
-and then attaching it with <code>AttachCurrentThread</code>).
-Now the stack trace looks like this:</p>
-<pre> dalvik.system.NativeStart.run(Native Method)</pre>
-
-<p>The topmost method is <code>NativeStart.run</code>, which isn't part of
-your application. If you call <code>FindClass</code> from this thread, the
-JavaVM will start in the "system" class loader instead of the one associated
-with your application, so attempts to find app-specific classes will fail.</p>
-
-<p>There are a few ways to work around this:</p>
-<ul>
- <li>Do your <code>FindClass</code> lookups once, in
- <code>JNI_OnLoad</code>, and cache the class references for later
- use. Any <code>FindClass</code> calls made as part of executing
- <code>JNI_OnLoad</code> will use the class loader associated with
- the function that called <code>System.loadLibrary</code> (this is a
- special rule, provided to make library initialization more convenient).
- If your app code is loading the library, <code>FindClass</code>
- will use the correct class loader.
- <li>Pass an instance of the class into the functions that need
- it, by declaring your native method to take a Class argument and
- then passing <code>Foo.class</code> in.
- <li>Cache a reference to the <code>ClassLoader</code> object somewhere
- handy, and issue <code>loadClass</code> calls directly. This requires
- some effort.
-</ul>
-
-
-<a name="faq_sharing" id="faq_sharing"></a>
-<h2>FAQ: How do I share raw data with native code?</h2>
-
-<p>You may find yourself in a situation where you need to access a large
-buffer of raw data from both managed and native code. Common examples
-include manipulation of bitmaps or sound samples. There are two
-basic approaches.</p>
-
-<p>You can store the data in a <code>byte[]</code>. This allows very fast
-access from managed code. On the native side, however, you're
-not guaranteed to be able to access the data without having to copy it. In
-some implementations, <code>GetByteArrayElements</code> and
-<code>GetPrimitiveArrayCritical</code> will return actual pointers to the
-raw data in the managed heap, but in others it will allocate a buffer
-on the native heap and copy the data over.</p>
-
-<p>The alternative is to store the data in a direct byte buffer. These
-can be created with <code>java.nio.ByteBuffer.allocateDirect</code>, or
-the JNI <code>NewDirectByteBuffer</code> function. Unlike regular
-byte buffers, the storage is not allocated on the managed heap, and can
-always be accessed directly from native code (get the address
-with <code>GetDirectBufferAddress</code>). Depending on how direct
-byte buffer access is implemented, accessing the data from managed code
-can be very slow.</p>
-
-<p>The choice of which to use depends on two factors:</p>
-<ol>
- <li>Will most of the data accesses happen from code written in Java
- or in C/C++?
- <li>If the data is eventually being passed to a system API, what form
- must it be in? (For example, if the data is eventually passed to a
- function that takes a byte[], doing processing in a direct
- <code>ByteBuffer</code> might be unwise.)
-</ol>
-
-<p>If there's no clear winner, use a direct byte buffer. Support for them
-is built directly into JNI, and performance should improve in future releases.</p>
diff --git a/docs/html/guide/topics/security/permissions.jd b/docs/html/guide/topics/security/permissions.jd
index 3013e38..4ad9b7c 100644
--- a/docs/html/guide/topics/security/permissions.jd
+++ b/docs/html/guide/topics/security/permissions.jd
@@ -61,6 +61,7 @@
are sandboxed in the same way and have the same degree of security from each
other.</p>
+
<a name="signing"></a>
<h2>Application Signing</h2>
@@ -112,7 +113,7 @@
<a name="permissions"></a>
<h2>Using Permissions</h2>
-<p>A basic Android application has no permissions associated with it,
+<p>A basic Android application has no permissions associated with it by default,
meaning it can not do anything that would adversely impact the user experience
or any data on the device. To make use of protected features of the device,
you must include in your <code>AndroidManifest.xml</code> one or more
@@ -165,6 +166,33 @@
</ul>
+
+<div class="caution">
+<p><strong>Caution:</strong> Over time,
+new restrictions may be added to the platform such that, in order
+to use certain APIs, your app must request a permission that it previously did not need.
+Because existing apps assume access to those APIs is freely available,
+Android may apply the new permission request to the app's manifest to avoid
+breaking the app on the new platform version.
+Android makes the decision as to whether an app might need the permission based on
+the value provided for the <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
+attribute. If the value is lower than the version in which the permission was added, then
+Android adds the permission.</p>
+<p>For example, the {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} permission was
+added in API level 4 to restrict access to the shared storage space. If your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
+is 3 or lower, this permission is added to your app on newer versions of Android.</p>
+<p>Beware that if this happens to your app, your app listing on Google Play will show these
+required permissions even though your app might not actually require them.</p>
+<p>To avoid this and remove the default permissions you don't need, always update your <a
+href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a>
+to be as high as possible. You can see which permissions were added with each release in the
+{@link android.os.Build.VERSION_CODES} documentation.</p>
+</div>
+
+
+
<a name="declaring"></a>
<h2>Declaring and Enforcing Permissions</h2>
diff --git a/docs/html/guide/topics/ui/controls/text.jd b/docs/html/guide/topics/ui/controls/text.jd
index 2d9d215..654883d 100644
--- a/docs/html/guide/topics/ui/controls/text.jd
+++ b/docs/html/guide/topics/ui/controls/text.jd
@@ -79,15 +79,23 @@
</pre>
-<p>There are several different input types available for different situations. You can find
-them all listed with the documentation for <a
-href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code
-android:inputType}</a>.</p>
+<p>There are several different input types available for different situations.
+Here are some of the more common values for
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a>:</p>
-<p class="note"><strong>Tip:</strong> To allow users to input long strings of text with line
-breaks, use the {@code "textMultiLine"} input type. By default, an {@link android.widget.EditText}
-object is restricted to one line of text and scrolls horizontally when the text exceeds the
-available width.</p>
+<dl>
+ <dt>{@code "text"}</dt>
+ <dd>Normal text keyboard.</dd>
+ <dt>{@code "textEmailAddress"}</dt>
+ <dd>Normal text keyboard with the @ character.</dd>
+ <dt>{@code "textUri"}</dt>
+ <dd>Normal text keyboard with the / character.</dd>
+ <dt>{@code "number"}</dt>
+ <dd>Basic number keypad.</dd>
+ <dt>{@code "phone"}</dt>
+ <dd>Phone-style keypad.</dd>
+</dl>
<h3 id="Behaviors">Controlling other behaviors</h3>
@@ -98,7 +106,25 @@
<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType">{@code
android:inputType}</a> attribute allows bitwise combinations so you can specify both a keyboard
-layout and one or more behaviors at once. For example, here's how you can collect a postal
+layout and one or more behaviors at once.</p>
+
+<p>Here are some of the common input type values that define keyboard behaviors:</p>
+
+<dl>
+ <dt>{@code "textCapSentences"}</dt>
+ <dd>Normal text keyboard that capitalizes the first letter for each new sentence.</dd>
+ <dt>{@code "textCapWords"}</dt>
+ <dd>Normal text keyboard that capitalizes every word. Good for titles or person names.</dd>
+ <dt>{@code "textAutoCorrect"}</dt>
+ <dd>Normal text keyboard that corrects commonly misspelled words.</dd>
+ <dt>{@code "textPassword"}</dt>
+ <dd>Normal text keyboard, but the characters entered turn into dots.</dd>
+ <dt>{@code "textMultiLine"}</dt>
+ <dd>Normal text keyboard that allow users to input long strings of text that include line
+breaks (carriage returns).</dd>
+</dl>
+
+<p>For example, here's how you can collect a postal
address, capitalize each word, and disable text suggestions:</p>
<pre>
@@ -177,7 +203,7 @@
public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
boolean handled = false;
if (actionId == EditorInfo.IME_ACTION_SEND) {
- // Send the user message
+ sendMessage();
handled = true;
}
return handled;
diff --git a/docs/html/guide/webapps/webview.jd b/docs/html/guide/webapps/webview.jd
index 9ea0a10..ce7fe27 100644
--- a/docs/html/guide/webapps/webview.jd
+++ b/docs/html/guide/webapps/webview.jd
@@ -162,7 +162,7 @@
Context mContext;
/** Instantiate the interface and set the context */
- JavaScriptInterface(Context c) {
+ WebAppInterface(Context c) {
mContext = c;
}
diff --git a/docs/html/images/code_templates/ba-dropdown.png b/docs/html/images/code_templates/ba-dropdown.png
new file mode 100644
index 0000000..dd9d855
--- /dev/null
+++ b/docs/html/images/code_templates/ba-dropdown.png
Binary files differ
diff --git a/docs/html/images/code_templates/ba-no-navigation.png b/docs/html/images/code_templates/ba-no-navigation.png
new file mode 100644
index 0000000..02ab451
--- /dev/null
+++ b/docs/html/images/code_templates/ba-no-navigation.png
Binary files differ
diff --git a/docs/html/images/code_templates/ba-tabs.png b/docs/html/images/code_templates/ba-tabs.png
new file mode 100644
index 0000000..3727684
--- /dev/null
+++ b/docs/html/images/code_templates/ba-tabs.png
Binary files differ
diff --git a/docs/html/images/code_templates/ba-title-strip.png b/docs/html/images/code_templates/ba-title-strip.png
new file mode 100644
index 0000000..b288cd5
--- /dev/null
+++ b/docs/html/images/code_templates/ba-title-strip.png
Binary files differ
diff --git a/docs/html/images/code_templates/full-screen-activity.png b/docs/html/images/code_templates/full-screen-activity.png
new file mode 100644
index 0000000..7eac4cd
--- /dev/null
+++ b/docs/html/images/code_templates/full-screen-activity.png
Binary files differ
diff --git a/docs/html/images/code_templates/login-activity.png b/docs/html/images/code_templates/login-activity.png
new file mode 100644
index 0000000..872ae41
--- /dev/null
+++ b/docs/html/images/code_templates/login-activity.png
Binary files differ
diff --git a/docs/html/images/code_templates/master-detail-flow.png b/docs/html/images/code_templates/master-detail-flow.png
new file mode 100644
index 0000000..35f0a03
--- /dev/null
+++ b/docs/html/images/code_templates/master-detail-flow.png
Binary files differ
diff --git a/docs/html/images/code_templates/settings-activity.png b/docs/html/images/code_templates/settings-activity.png
new file mode 100644
index 0000000..7872ec7
--- /dev/null
+++ b/docs/html/images/code_templates/settings-activity.png
Binary files differ
diff --git a/docs/html/images/iab-thumb.png b/docs/html/images/iab-thumb.png
new file mode 100644
index 0000000..91399af
--- /dev/null
+++ b/docs/html/images/iab-thumb.png
Binary files differ
diff --git a/docs/html/images/training/input/ime_autocorrect.png b/docs/html/images/training/input/ime_autocorrect.png
new file mode 100644
index 0000000..fd8371b
--- /dev/null
+++ b/docs/html/images/training/input/ime_autocorrect.png
Binary files differ
diff --git a/docs/html/images/training/input/ime_password.png b/docs/html/images/training/input/ime_password.png
new file mode 100644
index 0000000..6270c30
--- /dev/null
+++ b/docs/html/images/training/input/ime_password.png
Binary files differ
diff --git a/docs/html/index.jd b/docs/html/index.jd
index 0dc1757..e91b68c 100644
--- a/docs/html/index.jd
+++ b/docs/html/index.jd
@@ -4,38 +4,6 @@
page.metaDescription=The official site for Android developers. Provides the Android SDK and documentation for app developers and designers.
@jd:body
-<style>
-#butterbar-wrapper {
- position:absolute;
- top:0;
- left:0;
- width:100%;
-}
-#butterbar {
- width:940px;
- margin:0 auto;
-}
-#butterbar-message {
- background-color:#f80;
- float:right;
- font-size:12px;
- font-weight:bold;
- padding:0 10px;
- border-radius: 0 0 5px 5px;
-}
-#butterbar-message a {color:#fff !important}
-#butterbar-message a:hover {text-decoration:underline;}
-</style>
-
- <div id="butterbar-wrapper" >
- <div id="butterbar" >
- <div id="butterbar-message">
-<a target="_blank" href="https://docs.google.com/a/google.com/forms/d/17EFbvdm4FYkocc83EcrKhyhP5Y6tbns_eiBSeQ6ojxU/viewform">
- Take the Android Developer Survey</a>
- </div>
- </div>
-</div>
-
<div class="wrap">
<!-- Slideshow -->
diff --git a/docs/html/sdk/index.jd b/docs/html/sdk/index.jd
index 23c102e..961afda 100644
--- a/docs/html/sdk/index.jd
+++ b/docs/html/sdk/index.jd
@@ -3,42 +3,42 @@
page.metaDescription=Download the official Android SDK to develop apps for Android-powered devices.
sdk.win32_bundle_download=adt-bundle-windows-x86.zip
-sdk.win32_bundle_bytes=417851015
-sdk.win32_bundle_checksum=42d9a6c15113d405a97eed05e6d42e2b
+sdk.win32_bundle_bytes=418030942
+sdk.win32_bundle_checksum=ce32861d8f7c93ff6ff6971bd99d228e
sdk.win64_bundle_download=adt-bundle-windows-x86_64.zip
-sdk.win64_bundle_bytes=417851515
-sdk.win64_bundle_checksum=73bdd1168fce0e36a27255a4335c865d
+sdk.win64_bundle_bytes=418155677
+sdk.win64_bundle_checksum=f09aa4557bd1dc2703fde95dcdd6b92e
sdk.mac64_bundle_download=adt-bundle-mac-x86_64.zip
-sdk.mac64_bundle_bytes=382957959
-sdk.mac64_bundle_checksum=a320f8bbaee8572a36e68c434564bdd0
+sdk.mac64_bundle_bytes=383216991
+sdk.mac64_bundle_checksum=ea6c074ee30c426c503dab5c225a5076
sdk.linux32_bundle_download=adt-bundle-linux-x86.zip
-sdk.linux32_bundle_bytes=411065882
-sdk.linux32_bundle_checksum=39687b06fedfea7487ff0824a4d32ee8
+sdk.linux32_bundle_bytes=411205048
+sdk.linux32_bundle_checksum=e64594cd339b8d9a400b9d16c616b3c3
sdk.linux64_bundle_download=adt-bundle-linux-x86_64.zip
-sdk.linux64_bundle_bytes=411217430
-sdk.linux64_bundle_checksum=b0590fe9c1533da9b20ea65525b77677
+sdk.linux64_bundle_bytes=411478695
+sdk.linux64_bundle_checksum=582bfc9083ff4cbcfacc8223bd8c3be1
-sdk.win_installer=installer_r21-windows.exe
-sdk.win_installer_bytes=77523031
-sdk.win_installer_checksum=29ca8cb8f0bc8db627fa2adc2139a3cc
+sdk.win_installer=installer_r21.0.1-windows.exe
+sdk.win_installer_bytes=76520869
+sdk.win_installer_checksum=e2012262471a2583d4a559b15fcf45ff
-sdk.win_download=android-sdk_r21-windows.zip
-sdk.win_bytes=99093893
-sdk.win_checksum=7311452823470365f7975a545f8a2be4
+sdk.win_download=android-sdk_r21.0.1-windows.zip
+sdk.win_bytes=99107847
+sdk.win_checksum=613568d774c3bf25c5d24db16601af83
-sdk.mac_download=android-sdk_r21-macosx.zip
-sdk.mac_bytes=65792626
-sdk.mac_checksum=67e46adca90dd18d7291443f6c15d6af
+sdk.mac_download=android-sdk_r21.0.1-macosx.zip
+sdk.mac_bytes=65804128
+sdk.mac_checksum=30401c43a014cd5d6ec9d0c62854a1d9
-sdk.linux_download=android-sdk_r21-linux.tgz
-sdk.linux_bytes=91378351
-sdk.linux_checksum=7f8d73b629f808cdcfc9f9900bbd7580
+sdk.linux_download=android-sdk_r21.0.1-linux.tgz
+sdk.linux_bytes=91394975
+sdk.linux_checksum=eaa5a8d76d692d1d027f2bbcee019644
@@ -222,7 +222,7 @@
<input id="32" onclick="onAgreeChecked()" type="radio" name="bit" value="32">
<label for="32">32-bit</label>
<input id="64" onclick="onAgreeChecked()" type="radio" name="bit" value="64">
- <label for="64">64-bit</label>
+ <label for="64">64-bit</label>
</p>
<p><a href="" class="button disabled" id="downloadForRealz" onclick="return onDownloadForRealz(this);"></a></p>
</div>
@@ -241,7 +241,7 @@
<h1 style="margin-top:0">Get the Android SDK</h1>
-
+
<p>The Android SDK provides you the API libraries and developer tools necessary to build, test,
and debug apps for Android.</p>
@@ -290,7 +290,7 @@
-
+
<!-- alternative SDK options -->
<div class="col-13" style="margin:0;">
diff --git a/docs/html/sdk/installing/installing-adt.jd b/docs/html/sdk/installing/installing-adt.jd
index 93d1db6..804030b 100644
--- a/docs/html/sdk/installing/installing-adt.jd
+++ b/docs/html/sdk/installing/installing-adt.jd
@@ -1,8 +1,8 @@
page.title=Installing the Eclipse Plugin
-adt.zip.version=21.0.0
-adt.zip.download=ADT-21.0.0.zip
-adt.zip.bytes=13556487
-adt.zip.checksum=7db4eaae5df6a34fd853317a2bd8250b
+adt.zip.version=21.0.1
+adt.zip.download=ADT-21.0.1.zip
+adt.zip.bytes=13569302
+adt.zip.checksum=acfb01bf3fd1240f1fc21488c3dd16bf
@jd:body
diff --git a/docs/html/tools/projects/projects-eclipse.jd b/docs/html/tools/projects/projects-eclipse.jd
index f1972bc..af85015 100644
--- a/docs/html/tools/projects/projects-eclipse.jd
+++ b/docs/html/tools/projects/projects-eclipse.jd
@@ -27,7 +27,7 @@
<p>Eclipse and the ADT plugin provide GUIs and wizards to create all three types of projects
(Android project, Library project, and Test project):
-
+
<ul>
<li>An Android project contains all of the files and resources that are needed to build a project into
an .apk file for installation. You need to create an Android project for any application that you
@@ -44,99 +44,132 @@
<h2 id="CreatingAProject">Creating an Android Project</h2>
- <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new Android
- project (or a project from existing code). To create a new project:</p>
+ <p>The ADT plugin provides a <em>New Project Wizard</em> that you can use to quickly create a new
+ Android project (or a project from existing code). To create a new project:</p>
<ol>
<li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li>
- <li>Select <strong>Android</strong> > <strong>Android Project</strong>, and click
+ <li>Select <strong>Android</strong> > <strong>Android Application Project</strong>, and click
<strong>Next</strong>.</li>
- <li>Select the contents for the project:
+ <li>Enter the basic settings for the project:
<ul>
- <li>Enter a <em>Project Name</em>. This will be the name of the folder where your project
- is created.</li>
+ <li>Enter an <strong>Application Name</strong>. This name is used as the title of your
+ application launcher icon when it is installed on a device.</li>
- <li>Under Contents, select <strong>Create new project in workspace</strong>. Select your
- project workspace location.</li>
+ <li>Enter a <strong>Project Name</strong>. This text is used as the name of the folder where
+ your project is created.</li>
- <li>Under Target, select an Android target to be used as the project's Build Target. The
- Build Target specifies which Android platform you'd like your application built against.
+ <li>Enter a <strong>Package Name</strong>. This class package namespace creates the initial
+ package structure for your applications code files and is added as the
+ <a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">{@code package}</a>
+ attribute in your application's
+ <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">Android manifest file</a>.
+ This manifest value serves as the unique identifier for your application app when you
+ distribute it to users. The package name must follow the same rules as packages in the Java
+ programming language.</li>
- <p>Select the lowest platform with which your application is compatible.</p>
+ <li>Select a <strong>Minimum Required SDK</strong>. This setting indicates the lowest
+ version of the Android platform that your application supports. This value sets the
+ <code>minSdkVersion</code> attribute in the
+ <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a>
+ element of your manifest file.</li>
- <p class="note"><strong>Note:</strong> You can change your the Build Target for your
+ <li>Select a <strong>Target SDK</strong>. This setting indicates the highest version of
+ Android with which you have tested with your application and sets the
+ <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code
+ targetSdkVersion}</a> attribute in your application's' manifest file.
+
+ <p class="note"><strong>Note:</strong> You can change the target SDK for your
project at any time: Right-click the project in the Package Explorer, select
<strong>Properties</strong>, select <strong>Android</strong> and then check the desired
- Project Target.</p>
+ <strong>Project Build Target</strong>.</p>
</li>
- <li>Under Properties, fill in all necessary fields.
+ <li>Select a <strong>Compile With</strong> API version. This setting specifies what version
+ of the SDK to compile your project against. We strongly recommend using the most recent
+ version of the API.</li>
- <ul>
- <li>Enter an <em>Application name</em>. This is the human-readable title for your
- application — the name that will appear on the Android device.</li>
+ <li>Select a <strong>Theme</strong>. This setting specifies which standard Android
+ <a href="{@docRoot}design/style/themes.html">visual style</a> is applied to your
+ application.</li>
- <li>Enter a <em>Package name</em>. This is the package namespace (following the same
- rules as for packages in the Java programming language) where all your source code will
- reside.</li>
-
- <li>Select <em>Create Activity</em> (optional, of course, but common) and enter a name
- for your main Activity class.</li>
-
- <li>Enter a <em>Min SDK Version</em>. This is an integer that indicates the minimum API
- Level required to properly run your application. Entering this here automatically sets
- the <code>minSdkVersion</code> attribute in the <a href=
- "{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a> of your
- Android Manifest file. If you're unsure of the appropriate <a href=
- "{@docRoot}guide/topics/manifest/uses-sdk-element.html#ApiLevels">API Level</a> to use, copy the API Level
- listed for the Build Target you selected in the Target tab.</li>
- </ul>
- </li>
+ <li>Click <strong>Next</strong>.</li>
</ul>
</li>
- <li>Click <strong>Finish</strong>.</li>
+ <li>In the <strong>Configure Project</strong> page, select the desired settings and click
+ <strong>Next</strong>. Leave the <strong>Create activity</strong> option checked so you can
+ start your application with some essential components.</li>
+
+ <li>In the <strong>Configure Launcher Icon</strong> page, create an icon and click
+ <strong>Next</strong>.</li>
+
+ <li>In the <strong>Create Activity</strong> page, select activity template and click
+ <strong>Next</strong>. For more information about Android code templates, see
+ <a href="{@docRoot}tools/projects/templates.html">Using Code Templates</a>.
+ </li>
+
+ <li>Click <strong>Finish</strong> and the wizard creates a new project according to the options
+ you have chosen.</li>
</ol>
- <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard from the
- <em>New</em> icon in the toolbar.</p>
+ <p class="note"><strong>Tip:</strong> You can also start the New Project Wizard by clicking the
+ <strong>New</strong> <img src="/images/tools/eclipse-new.png"
+ style="vertical-align:baseline;margin:0"> icon in the toolbar.</p>
+
<h2 id="SettingUpLibraryProject">Setting up a Library Project</h2>
<p>A library project is a standard Android project, so you can create a new one in the same way
as you would a new application project.</p>
- <p>When you are creating the library project, you can select any application name, package, and
- set other fields as needed, as shown in figure 1.</p>
+ <p>To create a new library project:</p>
- <p>Next, set the project's properties to indicate that it is a library project:</p>
+ <ol>
+ <li>Select <strong>File</strong> > <strong>New</strong> > <strong>Project</strong>.</li>
+
+ <li>Select <strong>Android</strong> > <strong>Android Application Project</strong>, and click
+ <strong>Next</strong>.</li>
+
+ <li>Enter the basic settings for the project, including <strong>Application Name</strong>,
+ <strong>Project Name</strong>, <strong>Package Name</strong>, and SDK settings.</li>
+
+ <li>In the <strong>Configure Project</strong> page, select the <strong>Mark this project as a
+ library</strong> option to flag the project as a library.</li>
+
+ <li>Set the other options as desired and click <strong>Next</strong>.</li>
+
+ <li>Follow the instructions to complete the wizard and create a new library project.</li>
+ </ol>
+
+ <p>You can also convert an existing application project into a library. To do so, simply open the
+ Properties for the project and select the <strong>is Library</strong> checkbox, as shown in
+ the figure below.</p>
+
+ <img src= "{@docRoot}images/developing/adt-props-isLib.png">
+ <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an Android library.</p>
+
+ <p>To set the a project's properties to indicate that it is a library project:</p>
<ol>
<li>In the <strong>Package Explorer</strong>, right-click the library project and select
<strong>Properties</strong>.</li>
- <li>In the <strong>Properties</strong> window, select the "Android" properties group at left
- and locate the <strong>Library</strong> properties at right.</li>
+ <li>In the <strong>Properties</strong> window, select the <strong>Android</strong> properties
+ group in the left pane and locate the <strong>Library</strong> properties in the right pane.</li>
- <li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li>
+ <li>Select the <strong>is Library</strong> check box and click <strong>Apply</strong>.</li>
- <li>Click <strong>OK</strong> to close the <em>Properties</em> window.</li>
+ <li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li>
</ol>
- <p>The new project is now marked as a library project. You can begin moving source code and
- resources into it, as described in the sections below.</p>
+ <p>Once you create a library project or mark an existing project as a library, you can reference
+ the library project in other Android application projects. For more information, see the
+ <a href="#ReferencingLibraryProject">Referencing a library project</a> section.
- <p>You can also convert an existing application project into a library. To do so, simply open the
- Properties for the project and select the "is Library" checkbox. Other application projects can
- now reference the existing project as a library project.</p>
-
- <img src= "{@docRoot}images/developing/adt-props-isLib.png">
-
- <p class="img-caption"><strong>Figure 1.</strong> Marking a project as an
- Android library project.</p>
<h3>Creating the manifest file</h3>
@@ -146,7 +179,7 @@
<p>For example, the <a href=
"{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> example library
- project declares the Activity <code>GameActivity</code>:</p>
+ project declares the activity <code>GameActivity</code>:</p>
<pre>
<manifest>
...
@@ -167,6 +200,9 @@
<p>To add a reference to a library project, follow these steps:</p>
<ol>
+ <li>Make sure that both the project library and the application project that depends on it are
+ in your workspace. If one of the projects is missing, import it into your workspace.</li>
+
<li>In the <strong>Package Explorer</strong>, right-click the dependent project and select
<strong>Properties</strong>.</li>
@@ -214,7 +250,7 @@
<p>For example, the <a href=
"{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> example
- application declares the library Activity <code>GameActivity</code> like this:</p>
+ application declares the library activity <code>GameActivity</code> like this:</p>
<pre>
<manifest>
...
diff --git a/docs/html/tools/projects/templates.jd b/docs/html/tools/projects/templates.jd
new file mode 100644
index 0000000..fce24fd
--- /dev/null
+++ b/docs/html/tools/projects/templates.jd
@@ -0,0 +1,347 @@
+page.title=Using Code Templates
+@jd:body
+
+ <div id="qv-wrapper">
+ <div id="qv">
+ <h2>In this document</h2>
+
+ <ol>
+ <li><a href="#app-templates">Application Templates</a>
+ <ol>
+ <li><a href="#blank-activity">BlankActivity Template</a></li>
+ <li><a href="#full-screen-activity">Full Screen Activity Template</a></li>
+ <li><a href="#master-detail-activity">Master Detail Flow Template</a></li>
+ </ol>
+ </li>
+
+ <li><a href="#activity-templates">Activity Templates</a>
+ <ol>
+ <li><a href="#login-activity">Login Activity Template</a></li>
+ <li><a href="#settings-activity">Settings Activity Template</a></li>
+ </ol>
+ </li>
+ <li><a href="#object-templates">Other Templates</a></li>
+ </ol>
+
+ </div>
+ </div>
+
+
+<p>The SDK tools provide templates for quickly creating Android application projects with the basic
+ structure or for adding components to your existing projects. The code templates
+ provided by the Android SDK follow the Android design and development guidelines to get you on the
+ right track to creating a beautiful, functional application.</p>
+
+<p>There are several types of Android code templates, which can create anything from an entire
+ application down to specific application components. The main categories of code templates are as
+ follows:</p>
+
+<ul>
+ <li><a href="#app-templates">Application Templates</a></li>
+ <li><a href="#activity-templates">Activity Templates</a></li>
+ <li><a href="#object-templates">Other Templates</a></li>
+</ul>
+
+
+<h2 id="app-templates">Application Templates</h2>
+
+<p>Application templates create basic Android applications that you can immediately run and test
+ on your Android device. These templates are available when you create a new Android project,
+ though you can also use these templates to <a href="#activity-templates">add new activities</a>
+ to an existing project.</p>
+
+<p>To use Android application templates:</p>
+
+<ol>
+ <li>In Eclipse, with the Android Development Tools (ADT) plugin installed, select <strong>File
+ > New > Android</strong>.</li>
+ <li>Select <strong>Android > Android Application Project</strong>, and click
+ <strong>Next</strong>.</li>
+ <li>Enter the settings for your application, including <strong>Application Name</strong>,
+ <strong>Project Name</strong>, <strong>Package Name</strong>, API level settings and
+ presentation <strong>Theme</strong>, and click <strong>Next</strong>.</li>
+ <li>Enter the project configuration options, and click <strong>Next</strong>.</li>
+ <li>Optionally enter launcher icon settings, and click <strong>Next</strong>.</li>
+ <li>In the <strong>Create Activity</strong> page, select an application template to use.
+ <ul>
+ <li><a href="#blank-activity">BlankActivity</a></li>
+ <li><a href="#full-screen-activity">FullScreenActivity</a></li>
+ <li><a href="#master-detail-activity">MasterDetailFlow</a></li>
+ </ul>
+ </li>
+</ol>
+
+<p class="note">
+ <strong>Note:</strong> The other activity template options also create applications, however these
+ applications require further modification before they can be launched on an Android device.
+</p>
+
+
+<h3 id="blank-activity">Blank Activity Template</h3>
+
+<table>
+ <tr>
+ <th width="206px">Example</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/ba-no-navigation.png" alt="" />
+ </td>
+
+ <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+ None</strong> option creates a simple application that follows the
+ <a href="{@docRoot}design/index.html">Android Design</a> guidelines. Use this template to
+ create a basic, minimal app as a starting point for your project.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>Title bar ({@link android.app.ActionBar} on Android 3.0 and later)</li>
+ <li>Options menu (action overflow on Android 3.0 and later) </li>
+ <li>Basic layout</li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/ba-tabs.png" alt="" />
+ </td>
+
+ <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+ Tabs</strong> or <strong>Tabs + Swipe</strong> option creates an application with
+ three sections based on the {@link android.app.Fragment} class and a tabbed user
+ interface.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>{@link android.app.ActionBar} for tab controls</li>
+ <li>{@link android.app.Fragment} objects for section content</li>
+ <li>Optional swipe gesture support based on the
+ <a href="{@docRoot}design/patterns/swipe-views.html">swipe view</a> design pattern,
+ which extends {@link android.support.v4.app.FragmentPagerAdapter} to manage section
+ fragments</li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/ba-title-strip.png" alt="" />
+ </td>
+
+ <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+ Swipe Views + Title Strip</strong> option creates an application with three
+ {@link android.app.Fragment} sections, a compact title strip header (known as
+ <a href="{@docRoot}design/building-blocks/tabs.html#scrollable">Scrollable Tabs</a> in the
+ <a href="{@docRoot}design/index.html">Android Design</a> guide) and swipe navigation between
+ the sections, based on the <a href="{@docRoot}design/patterns/swipe-views.html">swipe
+ view</a> design pattern.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>{@link android.support.v4.view.PagerTitleStrip} for section titles</li>
+ <li>{@link android.app.Fragment} objects for section content</li>
+ <li>{@link android.support.v4.app.FragmentPagerAdapter} to manage section fragments</li>
+ </ul>
+ </td>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/ba-dropdown.png" alt="" />
+ </td>
+
+ <td><p>The <strong>BlankActivity</strong> template with the <strong>Navigation Type:
+ Dropdown</strong> option creates an application that extends
+ {@link android.support.v4.app.FragmentActivity}, containing three
+ {@link android.app.Fragment} sections, with an {@link android.app.ActionBar} using list mode
+ navigation.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>{@link android.app.ActionBar} for list mode navigation</li>
+ <li>{@link android.app.Fragment} objects for section content</li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="full-screen-activity">Full Screen Activity Template</h3>
+
+<table>
+ <tr>
+ <th width="240px">Example</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/full-screen-activity.png" alt="" />
+ </td>
+
+ <td><p>This template provides an implementation of an activity which alternates between a
+ primary, full screen view and a view with standard user interface controls, including the
+ notification bar and application title bar. The full screen view is the default and a user
+ can activate the standard view by touching the device screen.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>{@code SystemUiHider} implementation that manages hiding of the system user interface
+ using a version-compatible approach</li>
+ <li>Basic layout</li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="master-detail-activity">Master Detail Flow Template</h3>
+
+<table>
+ <tr>
+ <th width="350px">Example</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/master-detail-flow.png" alt=""/>
+ </td>
+
+ <td><p>This template creates an adaptive layout for a set of items and associated details. On a
+ tablet device, the item list and item details are displayed on the same screen. On a smaller
+ device, the list and details are displayed on separate screens.</p>
+
+ <p class="note">
+ <strong>Note:</strong> This template follows the recommendations of the
+ <a href="{@docRoot}training/multiscreen/index.html">Designing for Multiple Screens</a>
+ Android training.
+ </p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>Adaptive layout using
+ <a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"
+ >alternative resource</a> XML files</li>
+ <li>{@link android.support.v4.app.FragmentActivity}, {@link android.app.Fragment} and
+ {@link android.support.v4.app.ListFragment} implementations</li>
+ </ul></td>
+ </tr>
+</table>
+
+
+<h2 id="activity-templates">Activity Templates</h2>
+
+<p>Android activity templates provide options to add new activities to your existing
+ application.</p>
+
+<p>To use Android activity templates:</p>
+
+<ol>
+ <li>Right click the project folder of the Android application where you want to add an
+ activity.</li>
+ <li>Select <strong>New > Other...</strong></li>
+ <li>Select <strong>Android > Android Activity</strong>, and click <strong>Next</strong>.</li>
+ <li>Select an activity template, then follow the instructions to add it to your existing
+ application.
+ <ul>
+ <li><a href="#login-activity">LoginActivity</a></li>
+ <li><a href="#settings-activity">SettingsActivity</a></li>
+ <li><a href="#blank-activity">BlankActivity</a></li>
+ <li><a href="#full-screen-activity">FullScreenActivity</a></li>
+ <li><a href="#master-detail-activity">MasterDetailFlow</a></li>
+ </ul>
+ </li>
+</ol>
+
+<p>These templates create the same type of activity as they do when used as an application template,
+however the following templates create activities which are specifically intended to be used as part
+of an existing application.</p>
+
+
+<h3 id="login-activity">Login Activity Template</h3>
+
+<table>
+ <tr>
+ <th width="206px">Example</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/login-activity.png" alt="" />
+ </td>
+
+ <td><p>This activity template provides input fields and a sample implementation of
+ an {@link android.os.AsyncTask} that asks users to login or register with their credentials.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>Recommended user interface for requesting login information</li>
+ <li>{@link android.os.AsyncTask} implementation for handing network operations separately
+ from the main user interface thread</li>
+ <li>Progress indicator during network operations</li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+
+<h3 id="settings-activity">Settings Activity Template</h3>
+
+<table>
+ <tr>
+ <th width="206px">Example</th>
+
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td><img src="{@docRoot}images/code_templates/settings-activity.png" alt="" />
+ </td>
+
+ <td><p>This template extends the {@link android.preference.PreferenceActivity} class and uses an
+ XML file to create preference settings. This template also demonstrates how to implement
+ several data types for settings.</p>
+
+ <p>This template includes:</p>
+
+ <ul>
+ <li>Activity extending {@link android.preference.PreferenceActivity}</li>
+ <li>Preference values defined using XML files added to the {@code res/xml/} directory of
+ your project.</li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+
+<h2 id="object-templates">Other Templates</h2>
+
+<p>Android object templates provide options to add new components to your existing application,
+including the previously mentioned activities as well as the following additional items:</p>
+
+<p>To use Android object templates:</p>
+
+<ol>
+ <li>Right click the project folder of the Android application where you want to add a code
+ component.</li>
+ <li>Select <strong>New > Other...</strong></li>
+ <li>Select <strong>Android > Android Object</strong>, and click <strong>Next</strong>.</li>
+ <li>Select an object template, then follow the instructions to add it to your existing
+ application.
+ <ul>
+ <li>{@link android.content.BroadcastReceiver}</li>
+ <li>{@link android.content.ContentProvider}</li>
+ <li><a href="{@docRoot}guide/topics/ui/custom-components.html">Custom View</a></li>
+ <li>{@link android.app.Service}</li>
+ </ul>
+ </li>
+</ol>
diff --git a/docs/html/tools/sdk/eclipse-adt.jd b/docs/html/tools/sdk/eclipse-adt.jd
index f2ff07c..243683c 100644
--- a/docs/html/tools/sdk/eclipse-adt.jd
+++ b/docs/html/tools/sdk/eclipse-adt.jd
@@ -57,6 +57,125 @@
<div class="toggle-content opened">
<p><a href="#" onclick="return toggleContent(this)">
<img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img"
+ alt=""/>ADT 21.0.1</a> <em>(December 2012)</em>
+ </p>
+
+ <div class="toggle-content-toggleme">
+<dl>
+ <dt>Dependencies:</dt>
+
+ <dd>
+ <ul>
+ <li>Java 1.6 or higher is required for ADT 21.0.1.</li>
+ <li>Eclipse Helios (Version 3.6.2) or higher is required for ADT 21.0.1.</li>
+ <li>ADT 21.0.1 is designed for use with <a href="{@docRoot}tools/sdk/tools-notes.html">SDK
+ Tools r21.0.1</a>. If you haven't already installed SDK Tools r21.0.1 into your SDK, use the
+ Android SDK Manager to do so.</li>
+ </ul>
+ </dd>
+
+ <dt>General Notes:</dt>
+ <dd>
+ <ul>
+ <li>Build
+ <ul>
+ <li>Updated build to detect and handle package name conflicts between an application and
+ the libraries it depends on. Libraries cannot share package names unless all of them
+ share the same package name.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40152">Issue 40152</a>,
+ <a href="http://code.google.com/p/android/issues/detail?id=40273">Issue 40273</a>)
+ </li>
+ <li>Added a flag to disable dex merging to deal with cases where merging could generate
+ a broken dex file. If this happens to your project, add the following setting to your
+ {@code project.properties} file: {@code dex.disable.merger=true} This setting
+ causes the build system to revert to the older, slower dex processing that does not
+ pre-dex libraries.</li>
+ </ul>
+ </li>
+ </ul>
+ </dd>
+
+ <dt>Bug fixes:</dt>
+ <dd>
+ <ul>
+ <li>Lint
+ <ul>
+ <li>Corrected check for {@code 0px} values in style XML elements.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39601">Issue 39601</a>)
+ </li>
+ <li>Fixed incorrect flagging of formatting strings.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39758">Issue 39758</a>)
+ </li>
+ <li>Fixed problem where {@code tools:ignore} directive in the manifest file was ignored
+ by the Lint tool.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40136">Issue 40136</a>)
+ </li>
+ <li>Fixed problem with flagging a wakelock release inside a conditional.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40424">Issue 40424</a>)
+ </li>
+ <li>Fixed incorrect reporting of missing {@code layout_width} and {@code layout_height}
+ XML fields.
+ (<a href="http://code.google.com/p/android/issues/detail?id=38958">Issue 38958</a>)
+ </li>
+ <li>Fixed handling of custom namespace attributes.</li>
+ <li>Added fixes for filtering out library project warnings.</li>
+ <li>Removed warnings about missing classes before a build.</li>
+ </ul>
+ </li>
+
+ <li>Android Virtual Device Manager
+ <ul>
+ <li>Fixed handling of {@code devices.xml} file in other locales.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39704">Issue 39704</a>)
+ </li>
+ <li>Fixed problem where the AVD Manager would not allow you to create a new AVD using
+ the <strong>4.0" WVGA</strong> or <strong> 4.65" 720p</strong> device definitions.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39939">Issue 39939</a>)
+ </li>
+ <li>Fixed problem where deleted device definitions were not removed.</li>
+ <li>Fixed incorrect screen resolution setting for the Nexus One device definition.</li>
+ <li>Fixed problem where writing of an AVD settings file does not properly escape
+ {@code \\} path characters.</li>
+ </ul>
+ </li>
+
+ <li>Layout Editor
+ <ul>
+ <li>Fixed problem where layout cannot render strings starting with {@code \@}.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40222">Issue 40222</a>)
+ </li>
+ <li>Fixed preview error when using the {@code android:numColumns} attribute in a layout.
+ (<a href="http://code.google.com/p/android/issues/detail?id=21296">Issue 21296</a>)
+ </li>
+ <li>Fixed compatibility issue with IntelliJ layout preview caused by layout editor
+ deleting the {@code .android/devices.xml} file.</li>
+ <li>Added fixes to editor for {@link android.widget.GridLayout}.</li>
+ </ul>
+ </li>
+
+ <li>Added support for {@code ldrtl} and {@code ldltr} resource qualifiers.</li>
+ <li>Fixed problem where Android XML resources mistakenly get compiled into {@code *.out.xml}
+ output files, causing project errors.
+ (<a href="http://code.google.com/p/android/issues/detail?id=3767">Issue 3767</a>)</li>
+ <li>Fixed error which caused resource refresh operations to fail.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39213">Issue 39213</a>)</li>
+ <li>Updated the Custom View code template handle to library projects properly.</li>
+ <li>Fixed support for library string resources ({@code strings.xml}) when exporting an
+ application that references a library with string resources.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39751">Issue 39751</a>)</li>
+ <li>Fixed problem where bad AVD setting files caused Device Manager and graphical XML editors
+ to crash.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40400">Issue 40400</a>)</li>
+ </ul>
+ </dd>
+
+</dl>
+</div>
+</div>
+
+<div class="toggle-content closed">
+ <p><a href="#" onclick="return toggleContent(this)">
+ <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img"
alt=""/>ADT 21.0.0</a> <em>(November 2012)</em>
</p>
diff --git a/docs/html/tools/sdk/ndk/index.jd b/docs/html/tools/sdk/ndk/index.jd
index ad4fd7c..f3c9a44 100644
--- a/docs/html/tools/sdk/ndk/index.jd
+++ b/docs/html/tools/sdk/ndk/index.jd
@@ -1,19 +1,18 @@
ndk=true
-ndk.win_download=android-ndk-r8c-windows.zip
-ndk.win_bytes=233787657
-ndk.win_checksum=3ff1570fa4ea865b7702507ea43dbae4
+ndk.win_download=android-ndk-r8d-windows.zip
+ndk.win_bytes=327014028
+ndk.win_checksum=d78ec3d4ec15ad3b18b9f488a5763c23
-ndk.mac_download=android-ndk-r8c-darwin-x86.tar.bz2
-ndk.mac_bytes=214270840
-ndk.mac_checksum=74a23e9e058512121835e0d6932e72d5
+ndk.mac_download=android-ndk-r8d-darwin-x86.tar.bz2
+ndk.mac_bytes=308328942
+ndk.mac_checksum=5cd9ef9fb7e03943ee8c9e147e42e571
-ndk.linux_download=android-ndk-r8c-linux-x86.tar.bz2
-ndk.linux_bytes=179945337
-ndk.linux_checksum=b0851346ff90c9266bc050016a228319
+ndk.linux_download=android-ndk-r8d-linux-x86.tar.bz2
+ndk.linux_bytes=254644383
+ndk.linux_checksum=e1fa0379a3feb59f2f0865f1a90bd382
page.title=Android NDK
-
@jd:body
@@ -250,6 +249,170 @@
<div class="toggle-content opened">
<p><a href="#" onclick="return toggleContent(this)">
<img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img"
+ alt="">Android NDK, Revision 8d</a> <em>(December 2012)</em>
+ </p>
+
+ <div class="toggle-content-toggleme">
+ <dl>
+ <dt>Important changes:</dt>
+ <dd>
+ <ul>
+ <li>Added the GNU Compiler Collection (GCC) 4.7 compiler to the NDK. The GCC 4.6 compiler
+ is still the default, so you must to explicitly enable the new version as follows:
+ <ul>
+ <li>For {@code ndk-build}, export the {@code NDK_TOOLCHAIN_VERSION=4.7} variable
+ <em>or</em> add it to {@code Application.mk}.</li>
+ <li>For standalone builds, add the {@code --toolchain=} option to
+ {@code make-standalone-toolchain.sh}, for example:
+ <pre>--toolchain=arm-linux-androideabi-4.7</pre></li>
+ </ul>
+ <p class="note">
+ <strong>Note:</strong> This feature is experimental. Please try it and
+ <a href="http://code.google.com/p/android/issues/list">report any issues</a>.</p>
+ </li>
+ <li>Added {@code stlport} exception support via gabi++. Note that the new gabi++
+ depends on {@code dlopen} and related code, meaning that:
+ <ul>
+ <li>You can no longer build a <em>static</em> executable using the {@code -static}
+ option or include {@code libstlport_static.a} using
+ {@code APP_STL := stlport_static}. (You can still use the {@code -static} option
+ with a standalone toolchain.) Compiling a <em>dynamic</em> executable using
+ {@code include $(BUILD_EXECUTABLE)} continues to work because the compiler
+ automatically adds the {@code -ldl} option.</li>
+ <li>If your project links using {@code -nostdlib} and {-Wl,--no-undefined}, you
+ must manually include the {@code -ldl} option.</li>
+ </ul>
+ For more information, see {@code CPLUSPLUS-SUPPORT.html}.
+
+ <p class="note">
+ <strong>Note:</strong> This feature is experimental and works better with the GCC
+ 4.6/4.7 compilers than with GCC 4.4.3 or Clang 3.1. Please try it and
+ <a href="http://code.google.com/p/android/issues/list">report any issues</a>.</p>
+ </li>
+ <li>Added a {@code -mstack-protector-guard=} option for x86 to choose between a
+ <em>global</em> default path which is compatible with older Android C library (bionic)
+ and a new <em>tls</em> path (%gs:20) for {@code -fstack-protector},
+ {@code -fstack-protector-all} and {@code -fstack-protector-strong} using the GCC 4.6
+ and higher compilers.
+
+ <p class="note">
+ <strong>Note:</strong> The {@code -mstack-protector-guard} setting itself does not
+ enable any {@code -fstack-protector*} options.</p>
+ </li>
+ <li>Added {@code android_setCpu()} function to
+ {@code sources/android/cpufeatures/cpu-features.c} for use when auto-detection via
+ {@code /proc} is not possible in Android 4.1 and higher.
+ (<a href="http://code.google.com/p/chromium/issues/detail?id=164154">Chromium Issue
+ 164154</a>)</li>
+ </ul>
+ </dd>
+
+ <dt>Important bug fixes:</dt>
+ <dd>
+ <ul>
+ <li>Fixed unnecessary rebuild of object files when using the {@code ndk-build} script.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39810">Issue 39810</a>)</li>
+ <li>Fixed a linker failure with the NDK 8c release for Mac OS X 10.6.x that produced the
+ following error:
+ <pre>
+dyld: lazy symbol binding failed: Symbol not found: _memmem
+Referenced from: ...../arm-linux-androideabi/bin/ld
+Expected in: /usr/lib/libSystem.B.dylib</pre>
+ This problem was caused by building on Mac OS X 10.7, which produced binaries that were
+ not compatible with Mac OS 10.6.x and the NDK.
+ </li>
+ <li>Removed the {@code -x c++} options from the Clang++ standalone build script.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39089">Issue 39089</a>)</li>
+ <li>Fixed issues using the {@code NDK_TOOLCHAIN_VERSION=clang3.1} option in Cygwin.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39585">Issue 39585</a>)</li>
+ <li>Fixed the {@code make-standalone-toolchain.sh} script to allow generation of a
+ standalone toolchain using the Cygwin or MinGW environments. The resulting toolchain
+ can be used in Cygwin, MingGW or CMD.exe environments.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39915">Issue 39915</a>,
+ <a href="http://code.google.com/p/android/issues/detail?id=39585">Issue 39585</a>)</li>
+ <li>Added missing {@code SL_IID_ANDROIDBUFFERQUEUESOURCE} option in android-14 builds for
+ ARM and X86.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40625">Issue 40625</a>)</li>
+ <li>Fixed x86 CPU detection for the {@code ANDROID_CPU_X86_FEATURE_MOVBE} feature.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39317">Issue 39317</a>)</li>
+ <li>Fixed an issue preventing the Standard Template Library (STL) from using C++
+ sources that do not have a {@code .cpp} file extension.</li>
+ <li>Fixed GCC 4.6 ARM internal compiler error <em>at reload1.c:1061</em>.
+ (<a href="http://code.google.com/p/android/issues/detail?id=20862">Issue 20862</a>)</li>
+ <li>Fixed GCC 4.4.3 ARM internal compiler error <em>at emit-rtl.c:1954</em>.
+ (<a href="http://code.google.com/p/android/issues/detail?id=22336">Issue 22336</a>)</li>
+ <li>Fixed GCC 4.4.3 ARM internal compiler error <em>at postreload.c:396</em>.
+ (<a href="http://code.google.com/p/android/issues/detail?id=22345">Issue 22345</a>)</li>
+ <li>Fixed problem with GCC 4.6/4.7 skipping lambda functions.
+ (<a href="http://code.google.com/p/android/issues/detail?id=35933">Issue 35933</a>)</li>
+ </ul>
+ </dd>
+
+ <dt>Other bug fixes:</dt>
+ <dd>
+ <ul>
+ <li>NDK header file fixes:
+ <ul>
+ <li>Fixed {@code __WINT_TYPE__} and {@code wint_t} to be the same type.</li>
+ <li>Corrected typo in {@code android/bitmap.h}.
+ (<a href="http://code.google.com/p/android/issues/detail?id=15134">Issue 15134</a>)
+ </li>
+ <li>Corrected typo in {@code errno.h}.</li>
+ <li>Added check for the presence of {@code __STDC_VERSION__} in {@code sys/cdefs.h}.
+ (<a href="http://code.google.com/p/android/issues/detail?id=14627">Issue 14627</a>)
+ </li>
+ <li>Reorganized headers in {@code byteswap.h} and {@code dirent.h}.</li>
+ <li>Fixed {@code limits.h} to include {@code page.h} which provides {@code PAGE_SIZE}
+ settings.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39983">Issue 39983</a>)
+ </li>
+ <li>Fixed return type of {@code glGetAttribLocation()} and
+ {@code glGetUniformLocation()} from {@code int} to {@code GLint}.</li>
+ <li>Fixed {@code __BYTE_ORDER} constant for x86 builds.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39824">Issue 39824</a>)
+ </li>
+ </ul>
+ </li>
+ <li>Fixed {@code ndk-build} script to not overwrite {@code -Os} with {@code -O2} for ARM
+ builds.</li>
+ <li>Fixed build scripts to allow overwriting of {@code HOST_AWK}, {@code HOST_SED}, and
+ {@code HOST_MAKE} settings.</li>
+ <li>Fixed issue for {@code ld.gold} on {@code fsck_msdos} builds linking objects built by
+ the Intel C/C++ compiler (ICC).</li>
+ <li>Fixed ARM EHABI support in Clang to conform to specifications.</li>
+ <li>Fixed GNU Debugger (GDB) to shorten the time spent on walking the target's link map
+ during {@code solib} events.
+ (<a href="http://code.google.com/p/android/issues/detail?id=38402">Issue 38402</a>)</li>
+ <li>Fixed missing {@code libgcc.a} file when linking shared libraries.</li>
+ </ul>
+ </dd>
+
+ <dt>Other changes:</dt>
+ <dd>
+ <ul>
+ <li>Backported 64-bit built-in atomic functions for ARM to GCC 4.6.</li>
+ <li>Added documentation for audio output latency, along with other documentation and
+ fixes.</li>
+ <li>Fixed debug builds with Clang so that non-void functions now raise a {@code SIGILL}
+ signal for paths without a return statement.</li>
+ <li>Updated {@code make-standalone-toolchain.sh} to accept the suffix {@code -clang3.1}
+ which is equivalent to adding {@code --llvm-version=3.1} to the GCC 4.6 toolchain.</li>
+ <li>Updated GCC and Clang bug report URL to:
+ <a href="http://source.android.com/source/report-bugs.html">http://source.android.com/source/report-bugs.html</a></li>
+ <li>Added ARM ELF support to {@code llvm-objdump}.</li>
+ <li>Suppressed <em>treating c input as c++</em> warning for Clang builds.</li>
+ <li>Updated build so that only the 32-bit version of {@code libiberty.a} is built and
+ placed in {@code lib32/}.</li>
+ </ul>
+ </dd>
+ </dl>
+ </div>
+</div>
+
+
+<div class="toggle-content closed">
+ <p><a href="#" onclick="return toggleContent(this)">
+ <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img"
alt="">Android NDK, Revision 8c</a> <em>(November 2012)</em>
</p>
diff --git a/docs/html/tools/sdk/tools-notes.jd b/docs/html/tools/sdk/tools-notes.jd
index a5dfa5a..9349a4e 100644
--- a/docs/html/tools/sdk/tools-notes.jd
+++ b/docs/html/tools/sdk/tools-notes.jd
@@ -28,6 +28,109 @@
<div class="toggle-content opened">
<p><a href="#" onclick="return toggleContent(this)">
<img src="{@docRoot}assets/images/triangle-opened.png" class="toggle-content-img"
+ alt=""/>SDK Tools, Revision 21.0.1</a> <em>(December 2012)</em>
+ </p>
+
+ <div class="toggle-content-toggleme">
+
+ <dl>
+ <dt>Dependencies:</dt>
+ <dd>
+ <ul>
+ <li>Android SDK Platform-tools revision 16 or later.</li>
+ <li>If you are developing in Eclipse with ADT, note that the SDK Tools r21.0.1 is
+ designed for use with ADT 21.0.1 and later. If you haven't already, update your
+ <a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a> to 21.0.0.</li>
+ <li>If you are developing outside Eclipse, you must have
+ <a href="http://ant.apache.org/">Apache Ant</a> 1.8 or later.</li>
+ </ul>
+ </dd>
+
+ <dt>General Notes:</dt>
+ <dd>
+ <ul>
+ <li>Build
+ <ul>
+ <li>Updated build to detect and handle package name conflicts between an application and
+ the libraries it depends on. Libraries cannot share package names unless all of them
+ share the same package name.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40152">Issue 40152</a>,
+ <a href="http://code.google.com/p/android/issues/detail?id=40273">Issue 40273</a>)
+ </li>
+ <li>Added a flag to disable dex merging to deal with cases where merging could generate
+ a broken dex file. If this happens to your project, add the following setting to your
+ {@code project.properties} file: {@code dex.disable.merger=true} This setting
+ causes the build system to revert to the older, slower dex processing that does not
+ pre-dex libraries.</li>
+ </ul>
+ </li>
+
+ <li>Renderscript
+ <ul>
+ <li>Added support for
+ <a href="{@docRoot}guide/topics/renderscript/compute.html#filterscript">Filterscript</a>
+ compilation.</li>
+ <li>Added new project setting to control the Renderscript compilation target separately
+ from an Android project. Adding the following line to a {@code project.properties}
+ file causes Renderscript code to be compiled for Android API Level 17, while the
+ containing application can target a different (lower) API level:
+ <pre>renderscript.target = 17</pre>
+ Previously, the Renderscript compilation target was tied to the
+ {@code android:minSdkVersion} setting in the manifest.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40487">Issue 40487</a>)
+ </li>
+ </ul>
+ </li>
+
+ </ul>
+ </dd>
+
+
+ <dt>Bug fixes:</dt>
+ <dd>
+ <ul>
+ <li>Lint
+ <ul>
+ <li>Corrected check for {@code 0px} values in style XML elements.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39601">Issue 39601</a>)
+ </li>
+ <li>Fixed incorrect flagging of formatting strings.
+ (<a href="http://code.google.com/p/android/issues/detail?id=39758">Issue 39758</a>)
+ </li>
+ <li>Fixed problem where {@code tools:ignore} directive in the manifest file was ignored
+ by the Lint tool.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40136">Issue 40136</a>)
+ </li>
+ <li>Fixed problem with flagging a wakelock release inside a conditional.
+ (<a href="http://code.google.com/p/android/issues/detail?id=40424">Issue 40424</a>)
+ </li>
+ <li>Fixed incorrect reporting of missing {@code layout_width} and {@code layout_height}
+ XML fields.
+ (<a href="http://code.google.com/p/android/issues/detail?id=38958">Issue 38958</a>)
+ </li>
+ <li>Fixed handling of custom namespace attributes.</li>
+ <li>Added fixes for filtering out library project warnings.</li>
+ <li>Removed warnings about missing classes before a build.</li>
+ </ul>
+ </li>
+
+ <li>Fixed problem with UI Automator Viewer execution script where Android tools directory
+ is not set.</li>
+ <li>Fixed problem with the SDK Manager so that it auto-selects the most recently released
+ platform on startup.</li>
+ <li>Fixed Java finding script to look for the currently supported version of Java (1.6 or
+ higher).</li>
+ <li>Fixed the SDK Manager launcher in the ADT bundle so that it can properly launch the
+ SDK Manager program when it is placed at the root of the bundle.</li>
+ </ul>
+ </dd>
+ </dl>
+ </div>
+</div>
+
+<div class="toggle-content closed">
+ <p><a href="#" onclick="return toggleContent(this)">
+ <img src="{@docRoot}assets/images/triangle-closed.png" class="toggle-content-img"
alt=""/>SDK Tools, Revision 21</a> <em>(November 2012)</em>
</p>
@@ -37,14 +140,15 @@
<dt>Dependencies:</dt>
<dd>
<ul>
- <li>Android SDK Platform-tools revision 15 or later.</li>
+ <li>Android SDK Platform-tools revision 16 or later.</li>
<li>If you are developing in Eclipse with ADT, note that the SDK Tools r21 is designed
for use with ADT 21.0.0 and later. If you haven't already, update your
<a href="{@docRoot}tools/sdk/eclipse-adt.html">ADT Plugin</a> to 21.0.0.</li>
<li>If you are developing outside Eclipse, you must have
<a href="http://ant.apache.org/">Apache Ant</a> 1.8 or later.</li>
- </ul>
+ </ul>
</dd>
+
<dt>General Notes:</dt>
<dd>
<ul>
@@ -827,7 +931,7 @@
</ul>
</dd>
</dl>
- </div>
+</div>
</div>
<div class="toggle-content closed">
@@ -861,7 +965,7 @@
</ul>
</dd>
</dl>
- </div>
+</div>
</div>
<div class="toggle-content closed">
@@ -892,7 +996,7 @@
provides the equivalent library project support.</p>
</dd>
</dl>
- </div>
+</div>
</div>
<div class="toggle-content closed">
@@ -941,7 +1045,7 @@
</ul>
</dd>
</dl>
- </div>
+</div>
</div>
<div class="toggle-content closed">
@@ -991,7 +1095,7 @@
</ul>
</dd>
</dl>
- </div>
+</div>
</div>
<div class="toggle-content closed">
@@ -1055,6 +1159,6 @@
href="/tools/help/layoutopt.html">layoutopt</a>.</p>
</dd>
</dl>
- </div>
+</div>
</div>
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs
index 46665b2..4baa9c3 100644
--- a/docs/html/tools/tools_toc.cs
+++ b/docs/html/tools/tools_toc.cs
@@ -10,8 +10,8 @@
<div class="nav-section-header"><a href="<?cs var:toroot
?>sdk/index.html"><span class="en">Download</span></a></div>
<ul>
- <li><a href="<?cs var:toroot ?>sdk/installing/bundle.html">
- <span class="en">Setting Up the ADT Bundle</span></a></li>
+ <li><a href="<?cs var:toroot ?>sdk/installing/bundle.html">
+ <span class="en">Setting Up the ADT Bundle</span></a></li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>sdk/installing/index.html"><span class="en">Setting Up
@@ -19,12 +19,12 @@
<ul>
<li><a href="<?cs var:toroot ?>sdk/installing/installing-adt.html">
<span class="en">Installing the Eclipse Plugin</span></a></li>
- <li><a href="<?cs var:toroot ?>sdk/installing/adding-packages.html">
- <span class="en">Adding Platforms and Packages</span></a></li>
+ <li><a href="<?cs var:toroot ?>sdk/installing/adding-packages.html">
+ <span class="en">Adding Platforms and Packages</span></a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>sdk/exploring.html">
- <span class="en">Exploring the SDK</span></a></li>
+ <li><a href="<?cs var:toroot ?>sdk/exploring.html">
+ <span class="en">Exploring the SDK</span></a></li>
<li><a href="<?cs var:toroot ?>tools/sdk/ndk/index.html">Download the NDK</a>
</li>
</ul>
@@ -49,6 +49,7 @@
<ul>
<li><a href="/tools/projects/projects-eclipse.html"><span class="en">From Eclipse with ADT</span></a></li>
<li><a href="/tools/projects/projects-cmdline.html"><span class="en">From the Command Line</span></a></li>
+ <li><a href="/tools/projects/templates.html"><span class="en">Using Code Templates</span></a></li>
</ul>
</li>
diff --git a/docs/html/training/articles/perf-jni.jd b/docs/html/training/articles/perf-jni.jd
index a21e9fe..2abb000 100644
--- a/docs/html/training/articles/perf-jni.jd
+++ b/docs/html/training/articles/perf-jni.jd
@@ -32,12 +32,11 @@
code (written in C/C++). It's vendor-neutral, has support for loading code from
dynamic shared libraries, and while cumbersome at times is reasonably efficient.</p>
-<p>You really should read through the
-<a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/jniTOC.html">JNI spec for J2SE 6</a>
+<p>If you're not already familiar with it, read through the
+<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html">Java Native Interface Specification</a>
to get a sense for how JNI works and what features are available. Some
aspects of the interface aren't immediately obvious on
-first reading, so you may find the next few sections handy.
-There's a more detailed <a href="http://java.sun.com/docs/books/jni/html/jniTOC.html">JNI Programmer's Guide and Specification</a>.</p>
+first reading, so you may find the next few sections handy.</p>
<a name="JavaVM_and_JNIEnv" id="JavaVM_and_JNIEnv"></a>
diff --git a/docs/html/training/basics/fragments/support-lib.jd b/docs/html/training/basics/fragments/support-lib.jd
index ba10b78..cc867d3 100644
--- a/docs/html/training/basics/fragments/support-lib.jd
+++ b/docs/html/training/basics/fragments/support-lib.jd
@@ -12,7 +12,7 @@
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
- <li><a href="#Setup">Set Up Your Project With the Support Library</a></li>
+ <li><a href="#Setup">Set Up Your Project with the Support Library</a></li>
<li><a href="#Apis">Import the Support Library APIs</a></li>
</ol>
<h2>You should also read</h2>
@@ -23,7 +23,7 @@
</div>
<p>The Android <a href="{@docRoot}tools/extras/support-library.html">Support Library</a> provides a JAR
-file with an API library that allow you to use some of the more recent Android APIs in your app
+file with an API library that allows you to use some of the more recent Android APIs in your app
while running on earlier versions of Android. For instance, the Support Library provides a version
of the {@link android.app.Fragment} APIs that you can use on Android 1.6 (API level 4) and
higher.</p>
@@ -32,7 +32,7 @@
to build a dynamic app UI.</p>
-<h2 id="Setup">Set Up Your Project With the Support Library</h2>
+<h2 id="Setup">Set Up Your Project with the Support Library</h2>
<div class="figure" style="width:527px">
<img src="{@docRoot}images/training/basics/sdk-manager.png" alt="" />
@@ -43,7 +43,7 @@
<p>To set up your project:</p>
<ol>
- <li>Downlad the Android Support package using the SDK Manager</li>
+ <li>Download the Android Support package using the SDK Manager.</li>
<li>Create a <code>libs</code> directory at the top level of your Android project.</li>
<li>Locate the JAR file for the library you want to use and copy it into the <code>libs/</code>
diff --git a/docs/html/training/best-user-input.jd b/docs/html/training/best-user-input.jd
new file mode 100644
index 0000000..7f5ed15
--- /dev/null
+++ b/docs/html/training/best-user-input.jd
@@ -0,0 +1,9 @@
+page.title=Best Practices for User Input
+page.trainingcourse=true
+
+@jd:body
+
+
+
+<p>These classes cover various subjects of user input, such as
+touch screen gestures and text input through on-screen input methods and hardware keyboards.</p>
\ No newline at end of file
diff --git a/docs/html/training/gestures/detector.jd b/docs/html/training/gestures/detector.jd
new file mode 100644
index 0000000..06d0e98
--- /dev/null
+++ b/docs/html/training/gestures/detector.jd
@@ -0,0 +1,341 @@
+page.title=Detecting Common Gestures
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Tracking Movement
+next.link=movement.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#data">Gather Data</a></li>
+ <li><a href="#detect">Detect Gestures</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>A "touch gesture" occurs when a user places one or more fingers on the touch
+screen, and your application interprets
+that pattern of touches as a particular gesture. There are correspondingly two
+phases to gesture detection:</p>
+
+<ol>
+ <li>Gathering data about touch events.</li>
+
+ <li>Interpreting the data to see if it meets the criteria for any of the
+gestures your app supports. </li>
+
+</ol>
+
+<h4>Support Library Classes</h4>
+
+<p>The examples in this lesson use the {@link android.support.v4.view.GestureDetectorCompat}
+and {@link android.support.v4.view.MotionEventCompat} classes. These classes are in the
+<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>. You should use
+Support Library classes where possible to provide compatibility with devices
+running Android 1.6 and higher. Note that {@link android.support.v4.view.MotionEventCompat} is <em>not</em> a
+replacement for the {@link android.view.MotionEvent} class. Rather, it provides static utility
+methods to which you pass your {@link android.view.MotionEvent} object in order to receive
+the desired action associated with that event.</p>
+
+<h2 id="data">Gather Data</h2>
+
+<p>When a user places one or more fingers on the screen, this triggers the
+callback {@link android.view.View#onTouchEvent onTouchEvent()}
+on the View that received the touch events.
+For each sequence of touch events (position, pressure, size, addition of another finger, etc.)
+that is ultimately identified as a gesture,
+{@link android.view.View#onTouchEvent onTouchEvent()} is fired several times.</p>
+
+<p>The gesture starts when the user first touches the screen, continues as the system tracks
+the position of the user's finger(s), and ends by capturing the final event of
+the user's fingers leaving the screen. Throughout this interaction,
+the {@link android.view.MotionEvent} delivered to {@link android.view.View#onTouchEvent onTouchEvent()}
+provides the details of every interaction. Your app can use the data provided by the {@link android.view.MotionEvent}
+to determine if a gesture it cares
+about happened.</p>
+
+<h3>Capturing touch events for an Activity or View</h3>
+
+<p><p>To intercept touch events in an Activity or View, override
+the {@link android.view.View#onTouchEvent onTouchEvent()} callback.</p>
+
+<p>The following snippet uses
+{@link android.support.v4.view.MotionEventCompat#getActionMasked getActionMasked()}
+to extract the action the user performed from the {@code event} parameter. This gives you the raw
+data you need to determine if a gesture you care about occurred:</p>
+
+<pre>
+public class MainActivity extends Activity {
+...
+// This example shows an Activity, but you would use the same approach if
+// you were subclassing a View.
+@Override
+public boolean onTouchEvent(MotionEvent event){
+
+ int action = MotionEventCompat.getActionMasked(event);
+
+ switch(action) {
+ case (MotionEvent.ACTION_DOWN) :
+ Log.d(DEBUG_TAG,"Action was DOWN");
+ return true;
+ case (MotionEvent.ACTION_MOVE) :
+ Log.d(DEBUG_TAG,"Action was MOVE");
+ return true;
+ case (MotionEvent.ACTION_UP) :
+ Log.d(DEBUG_TAG,"Action was UP");
+ return true;
+ case (MotionEvent.ACTION_CANCEL) :
+ Log.d(DEBUG_TAG,"Action was CANCEL");
+ return true;
+ case (MotionEvent.ACTION_OUTSIDE) :
+ Log.d(DEBUG_TAG,"Movement occurred outside bounds " +
+ "of current screen element");
+ return true;
+ default :
+ return super.onTouchEvent(event);
+ }
+}</pre>
+
+<p>You can then do your own processing on these events to determine if a
+gesture occurred. This is the kind of processing you would have to do for a
+custom gesture. However, if your app uses
+common gestures such as double tap, long press, fling, and so on, you can
+take advantage of the {@link
+android.view.GestureDetector} class. {@link
+android.view.GestureDetector} makes it easy for you to detect common
+gestures without processing the individual touch events yourself. This is
+discussed below in <a href="#detect">Detect Gestures</a>.</p>
+
+<h3>Capturing touch events for a single view</h3>
+
+<p>As an alternative to {@link android.view.View#onTouchEvent onTouchEvent()},
+you can attach an {@link android.view.View.OnTouchListener} object to any {@link
+android.view.View} object using the {@link android.view.View#setOnTouchListener
+setOnTouchListener()} method. This makes it possible to to listen for touch
+events without subclassing an existing {@link android.view.View}. For
+example:</p>
+
+<pre>View myView = findViewById(R.id.my_view);
+myView.setOnTouchListener(new OnTouchListener() {
+ public boolean onTouch(View v, MotionEvent event) {
+ // ... Respond to touch events
+ return true;
+ }
+});</pre>
+
+<p>Beware of creating a listener that returns {@code false} for the
+{@link android.view.MotionEvent#ACTION_DOWN} event. If you do this, the listener will
+not be called for the subsequent {@link android.view.MotionEvent#ACTION_MOVE}
+and {@link android.view.MotionEvent#ACTION_UP} string of events. This is because
+{@link android.view.MotionEvent#ACTION_DOWN} is the starting point for all touch events.</p>
+
+<p>If you are creating a custom View, you can override
+{@link android.view.View#onTouchEvent onTouchEvent()},
+as described above.</p>
+
+<h2 id="detect">Detect Gestures</h2>
+
+<p>Android provides the {@link android.view.GestureDetector} class for detecting
+common gestures. Some of the gestures it supports include {@link
+android.view.GestureDetector.OnGestureListener#onDown onDown()}, {@link
+android.view.GestureDetector.OnGestureListener#onLongPress onLongPress()},
+{@link android.view.GestureDetector.OnGestureListener#onFling onFling()}, and so
+on. You can use {@link android.view.GestureDetector} in conjunction with the
+{@link android.view.View#onTouchEvent onTouchEvent()}
+method described above.</p>
+
+
+<h3>Detecting All Supported Gestures</h3>
+
+<p>When you instantiate a {@link android.support.v4.view.GestureDetectorCompat}
+object, one of the parameters it takes is a class that implements the
+{@link android.view.GestureDetector.OnGestureListener} interface.
+{@link android.view.GestureDetector.OnGestureListener} notifies users when
+a particular touch event has occurred. To make it possible for your
+{@link android.view.GestureDetector} object to receive events, you override
+the View or Activity's {@link android.view.View#onTouchEvent onTouchEvent()} method,
+and pass along all observed events to the detector instance.</p>
+
+
+<p>In the following snippet, a return value of {@code true} from the individual
+{@code on<em><TouchEvent></em>} methods indicates that you
+have handled the touch event. A return value of {@code false} passes events down
+through the view stack until the touch has been successfully handled.</p>
+
+<p>Run the following snippet to get a feel for how actions are triggered when
+you interact with the touch screen, and what the contents of the {@link
+android.view.MotionEvent} are for each touch event. You will realize how much
+data is being generated for even simple interactions.</p>
+
+<pre>public class MainActivity extends Activity implements
+ GestureDetector.OnGestureListener,
+ GestureDetector.OnDoubleTapListener{
+
+ private static final String DEBUG_TAG = "Gestures";
+ private GestureDetectorCompat mDetector;
+
+ // Called when the activity is first created.
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_main);
+ // Instantiate the gesture detector with the
+ // application context and an implementation of
+ // GestureDetector.OnGestureListener
+ mDetector = new GestureDetectorCompat(this,this);
+ // Set the gesture detector as the double tap
+ // listener.
+ mDetector.setOnDoubleTapListener(this);
+ }
+
+ @Override
+ public boolean onTouchEvent(MotionEvent event){
+ this.mDetector.onTouchEvent(event);
+ // Be sure to call the superclass implementation
+ return super.onTouchEvent(event);
+ }
+
+ @Override
+ public boolean onDown(MotionEvent event) {
+ Log.d(DEBUG_TAG,"onDown: " + event.toString());
+ return true;
+ }
+
+ @Override
+ public boolean onFling(MotionEvent event1, MotionEvent event2,
+ float velocityX, float velocityY) {
+ Log.d(DEBUG_TAG, "onFling: " + event1.toString()+event2.toString());
+ return true;
+ }
+
+ @Override
+ public void onLongPress(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onLongPress: " + event.toString());
+ }
+
+ @Override
+ public boolean onScroll(MotionEvent e1, MotionEvent e2, float distanceX,
+ float distanceY) {
+ Log.d(DEBUG_TAG, "onScroll: " + e1.toString()+e2.toString());
+ return true;
+ }
+
+ @Override
+ public void onShowPress(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onShowPress: " + event.toString());
+ }
+
+ @Override
+ public boolean onSingleTapUp(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onSingleTapUp: " + event.toString());
+ return true;
+ }
+
+ @Override
+ public boolean onDoubleTap(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onDoubleTap: " + event.toString());
+ return true;
+ }
+
+ @Override
+ public boolean onDoubleTapEvent(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onDoubleTapEvent: " + event.toString());
+ return true;
+ }
+
+ @Override
+ public boolean onSingleTapConfirmed(MotionEvent event) {
+ Log.d(DEBUG_TAG, "onSingleTapConfirmed: " + event.toString());
+ return true;
+ }
+}</pre>
+
+<h3>Detecting a Subset of Supported Gestures</h3>
+
+<p>If you only want to process a few gestures, you can extend {@link
+android.view.GestureDetector.SimpleOnGestureListener} instead of implementing
+the {@link android.view.GestureDetector.OnGestureListener} interface. </p>
+<p>
+{@link
+android.view.GestureDetector.SimpleOnGestureListener} provides an implementation
+for all of the {@code on<em><TouchEvent></em>} methods by returning {@code false}
+for all of them. Thus you can override only the methods you care about.
+For
+example, the snippet below creates a class that extends {@link
+android.view.GestureDetector.SimpleOnGestureListener} and overrides {@link
+android.view.GestureDetector.OnGestureListener#onFling onFling()} and {@link
+android.view.GestureDetector.OnGestureListener#onDown onDown()}.</p>
+
+<p>Whether or not you use {@link android.view.GestureDetector.OnGestureListener},
+it's best practice to implement an
+{@link android.view.GestureDetector.OnGestureListener#onDown onDown()}
+method that returns {@code true}. This is because all gestures begin with an
+{@link android.view.GestureDetector.OnGestureListener#onDown onDown()} message. If you return
+{@code false} from {@link android.view.GestureDetector.OnGestureListener#onDown onDown()},
+as {@link android.view.GestureDetector.SimpleOnGestureListener} does by default,
+the system assumes that you want to ignore the rest of the gesture, and the other methods of
+{@link android.view.GestureDetector.OnGestureListener} never get called.
+This has the potential to cause unexpected problems in your app.
+The only time you should return {@code false} from
+{@link android.view.GestureDetector.OnGestureListener#onDown onDown()}
+is if you truly want to ignore an entire gesture. </p>
+
+<pre>public class MainActivity extends Activity {
+
+ private GestureDetectorCompat mDetector;
+
+ @Override
+ public void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_main);
+ mDetector = new GestureDetectorCompat(this, new MyGestureListener());
+ }
+
+ @Override
+ public boolean onTouchEvent(MotionEvent event){
+ this.mDetector.onTouchEvent(event);
+ return super.onTouchEvent(event);
+ }
+
+ class MyGestureListener extends GestureDetector.SimpleOnGestureListener {
+ private static final String DEBUG_TAG = "Gestures";
+
+ @Override
+ public boolean onDown(MotionEvent event) {
+ Log.d(DEBUG_TAG,"onDown: " + event.toString());
+ return true;
+ }
+
+ @Override
+ public boolean onFling(MotionEvent event1, MotionEvent event2,
+ float velocityX, float velocityY) {
+ Log.d(DEBUG_TAG, "onFling: " + event1.toString()+event2.toString());
+ return true;
+ }
+ }
+}
+</pre>
+
+
diff --git a/docs/html/training/gestures/index.jd b/docs/html/training/gestures/index.jd
new file mode 100644
index 0000000..0191450
--- /dev/null
+++ b/docs/html/training/gestures/index.jd
@@ -0,0 +1,94 @@
+page.title=Using Touch Gestures
+trainingnavtop=true
+startpage=true
+next.title=Detect Built-in Gestures
+next.link=detector.html
+
+
+@jd:body
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+
+<ul>
+ <li>Android 1.6 (API Level 4) or higher</li>
+</ul>
+<h2>You should also read</h2>
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p> This class describes how to write apps that allow users to interact with an
+app via touch gestures. Android provides a variety of APIs to
+help you create and detect gestures.</p>
+
+<p>Although your app should not depend on touch gestures for basic behaviors (since the gestures
+may not be available to all users in all contexts), adding touch-based
+interaction to your app can greatly increase its usefulness and appeal.</p>
+
+<p>To
+provide users with a consistent, intuitive experience, your app should follow
+the accepted Android conventions for touch gestures. The <a
+href="http://developer.android.com/design/patterns/gestures.html">Gestures
+design guide</a><a href="{@docRoot}design/patterns/notifications.html"></a>
+shows you how to use common gestures in Android apps. Also see the Design Guide
+for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a>. </p>
+
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt>
+ <strong><a href="detector.html">Detecting Common Gestures</a></strong>
+ </dt>
+ <dd>
+ Learn how to detect basic touch gestures such as scrolling, flinging, and double-tapping, using
+ {@link android.view.GestureDetector}.
+ </dd>
+
+<dt>
+ <strong><a href="movement.html">Tracking Movement</a></strong>
+ </dt>
+ <dd>
+ Learn how to track movement.
+ </dd>
+
+<dt>
+ <strong><a href="scroll.html">Animating a Scroll Gesture</a></strong>
+ </dt>
+ <dd>
+ Learn how to use scrollers ({@link android.widget.Scroller} or {@link
+android.widget.OverScroller}) to produce a scrolling animation in response to a
+touch event. </dd>
+
+<dt>
+ <strong><a href="multi.html">Handling Multi-Touch Gestures</a></strong>
+ </dt>
+ <dd>
+ Learn how to detect multi-pointer (finger) gestures.
+ </dd>
+<dt>
+ <strong><a href="scale.html">Dragging and Scaling</a></strong>
+ </dt>
+ <dd>
+ Learn how to implement touch-based dragging and scaling.
+ </dd>
+
+
+<dt><strong><a href="viewgroup.html">Managing Touch Events in a ViewGroup</a></strong></dt>
+
+ <dd>Learn how to manage touch events in a {@link android.view.ViewGroup} to
+ensure that touch events are correctly dispatched to their target views.</dd>
+</dl>
diff --git a/docs/html/training/gestures/movement.jd b/docs/html/training/gestures/movement.jd
new file mode 100644
index 0000000..f2c49d7
--- /dev/null
+++ b/docs/html/training/gestures/movement.jd
@@ -0,0 +1,151 @@
+page.title=Tracking Movement
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Animating a Scroll Gesture
+next.link=scroll.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#velocity">Track Velocity</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>This lesson describes how to track movement in touch events.</p>
+
+<p>A new {@link
+android.view.View#onTouchEvent onTouchEvent()} is triggered with an {@link
+android.view.MotionEvent#ACTION_MOVE} event whenever the current touch contact
+position, pressure, or size changes. As described in <a
+href="detector.html">Detecting Common Gestures</a>, all of these events are
+recorded in the {@link android.view.MotionEvent} parameter of {@link
+android.view.View#onTouchEvent onTouchEvent()}.</p>
+
+<p>Because finger-based touch isn't always the most precise form of interaction,
+detecting touch events is often based more on movement than on simple contact.
+To help apps distinguish between movement-based gestures (such as a swipe) and
+non-movement gestures (such as a single tap), Android includes the notion of
+"touch slop." Touch slop refers to the distance in pixels a user's touch can wander
+before the gesture is interpreted as a movement-based gesture. For more discussion of this
+topic, see <a href="viewgroup.html#vc">Managing Touch Events in a ViewGroup</a>.</p>
+
+
+
+<p>There are several different ways to track movement in a gesture, depending on
+the needs of your application. For example:</p>
+
+<ul>
+
+<li>The starting and ending position of a pointer (for example, move an
+on-screen object from point A to point B).</li>
+
+<li>The direction the pointer is traveling in, as determined by the x and y coordinates.</li>
+
+<li>History. You can find the size of a gesture's history by calling the {@link
+android.view.MotionEvent} method {@link android.view.MotionEvent#getHistorySize
+getHistorySize()}. You can then obtain the positions, sizes, time, and pressures
+of each of the historical events by using the motion event's {@code
+getHistorical<em><Value></em>} methods. History is useful when rendering a trail of the user's finger,
+such as for touch drawing. See the {@link android.view.MotionEvent} reference for
+details.</li>
+
+<li>The velocity of the pointer as it moves across the touch screen.</li>
+
+</ul>
+
+
+
+<h2 id="velocity">Track Velocity</h2>
+
+<p> You could have a movement-based gesture that is simply based on the distance and/or direction the pointer traveled. But velocity often is a
+determining factor in tracking a gesture's characteristics or even deciding
+whether the gesture occurred. To make velocity calculation easier, Android
+provides the {@link android.view.VelocityTracker} class and the
+{@link android.support.v4.view.VelocityTrackerCompat} class in the
+<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>.
+{@link
+android.view.VelocityTracker} helps you track the velocity of touch events. This
+is useful for gestures in which velocity is part of the criteria for the
+gesture, such as a fling.</p>
+
+
+<p>Here is a simple example that illustrates the purpose of the methods in the
+{@link android.view.VelocityTracker} API:</p>
+
+<pre>public class MainActivity extends Activity {
+ private static final String DEBUG_TAG = "Velocity";
+ ...
+ private VelocityTracker mVelocityTracker = null;
+ @Override
+ public boolean onTouchEvent(MotionEvent event) {
+ int index = event.getActionIndex();
+ int action = event.getActionMasked();
+ int pointerId = event.getPointerId(index);
+
+ switch(action) {
+ case MotionEvent.ACTION_DOWN:
+ if(mVelocityTracker == null) {
+ // Retrieve a new VelocityTracker object to watch the velocity of a motion.
+ mVelocityTracker = VelocityTracker.obtain();
+ }
+ else {
+ // Reset the velocity tracker back to its initial state.
+ mVelocityTracker.clear();
+ }
+ // Add a user's movement to the tracker.
+ mVelocityTracker.addMovement(event);
+ break;
+ case MotionEvent.ACTION_MOVE:
+ mVelocityTracker.addMovement(event);
+ // When you want to determine the velocity, call
+ // computeCurrentVelocity(). Then call getXVelocity()
+ // and getYVelocity() to retrieve the velocity for each pointer ID.
+ mVelocityTracker.computeCurrentVelocity(1000);
+ // Log velocity of pixels per second
+ // Best practice to use VelocityTrackerCompat where possible.
+ Log.d("", "X velocity: " +
+ VelocityTrackerCompat.getXVelocity(mVelocityTracker,
+ pointerId));
+ Log.d("", "Y velocity: " +
+ VelocityTrackerCompat.getYVelocity(mVelocityTracker,
+ pointerId));
+ break;
+ case MotionEvent.ACTION_UP:
+ case MotionEvent.ACTION_CANCEL:
+ // Return a VelocityTracker object back to be re-used by others.
+ mVelocityTracker.recycle();
+ break;
+ }
+ return true;
+ }
+}
+</pre>
+
+<p class="note"><strong>Note:</strong> Note that you should calculate velocity after an
+{@link android.view.MotionEvent#ACTION_MOVE} event,
+not after {@link android.view.MotionEvent#ACTION_UP}. After an {@link android.view.MotionEvent#ACTION_UP},
+the X and Y velocities will be 0.
+</p>
diff --git a/docs/html/training/gestures/multi.jd b/docs/html/training/gestures/multi.jd
new file mode 100644
index 0000000..d4c5b1d
--- /dev/null
+++ b/docs/html/training/gestures/multi.jd
@@ -0,0 +1,168 @@
+page.title=Handling Multi-Touch Gestures
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Dragging and Scaling
+next.link=scale.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#track">Track Multiple Pointers</a></li>
+ <li><a href="#action">Get a MotionEvent's Action</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>A multi-touch gesture is when multiple pointers (fingers) touch the screen
+at the same time. This lesson describes how to detect gestures that involve
+multiple pointers.</p>
+
+<h2 id="track">Track Multiple Pointers</h2>
+
+<p>When multiple pointers touch the screen at the same time, the system generates the
+following touch events:</p>
+
+<ul>
+ <li>{@link android.view.MotionEvent#ACTION_DOWN}—For the first pointer that
+touches the screen. This starts the gesture. The pointer data for this pointer is
+always at index 0 in the {@link android.view.MotionEvent}.</li>
+ <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_DOWN}—For
+extra pointers that enter the screen beyond the first. The pointer data for this
+pointer is at the index returned by {@link android.support.v4.view.MotionEventCompat#getActionIndex getActionIndex()}.</li>
+ <li>{@link android.view.MotionEvent#ACTION_MOVE}—A change has happened during a press gesture.</li>
+ <li>{@link android.support.v4.view.MotionEventCompat#ACTION_POINTER_UP}—Sent when a non-primary pointer goes up.</li>
+ <li>{@link android.view.MotionEvent#ACTION_UP}—Sent when the last pointer leaves the screen.</li>
+</ul>
+
+<p>You keep track of individual pointers within a {@link
+android.view.MotionEvent} via each pointer's index and ID:</p>
+
+<ul>
+<li><strong>Index</strong>: A {@link android.view.MotionEvent} effectively
+stores information about each pointer in an array. The index of a pointer is its position
+within this array. Most of the {@link
+android.view.MotionEvent} methods you use to interact with pointers take the
+pointer index as a parameter, not the pointer ID. </li>
+
+
+ <li><strong>ID</strong>: Each pointer also has an ID mapping that stays
+persistent across touch events to allow tracking an individual pointer across
+the entire gesture.</li>
+
+</ul>
+
+<p>The order in which individual pointers appear within a motion event is
+undefined. Thus the index of a pointer can change from one event to the
+next, but the pointer ID of a pointer is guaranteed to remain constant as long
+as the pointer remains active. Use the {@link
+android.view.MotionEvent#getPointerId getPointerId()} method to obtain a
+pointer's ID to track the pointer across all subsequent motion events in a
+gesture. Then for successive motion events, use the {@link
+android.view.MotionEvent#findPointerIndex findPointerIndex()} method to obtain
+the pointer index for a given pointer ID in that motion event. For example:</p>
+
+
+<pre>private int mActivePointerId;
+
+public boolean onTouchEvent(MotionEvent event) {
+ ....
+ // Get the pointer ID
+ mActivePointerId = event.getPointerId(0);
+
+ // ... Many touch events later...
+
+ // Use the pointer ID to find the index of the active pointer
+ // and fetch its position
+ int pointerIndex = event.findPointerIndex(mActivePointerId);
+ // Get the pointer's current position
+ float x = event.getX(pointerIndex);
+ float y = event.getY(pointerIndex);
+}</pre>
+
+<h2 id="action">Get a MotionEvent's Action</h2>
+
+<p>You should always use the method
+{@link android.view.MotionEvent#getActionMasked getActionMasked()} (or better yet, the compatability version
+{@link android.support.v4.view.MotionEventCompat#getActionMasked MotionEventCompat.getActionMasked()}) to retrieve
+the action of a
+{@link android.view.MotionEvent}. Unlike the older {@link android.view.MotionEvent#getAction getAction()}
+method, {@link android.support.v4.view.MotionEventCompat#getActionMasked getActionMasked()} is designed to work with
+multiple pointers. It returns the masked action
+being performed, without including the pointer index bits. You can then use
+{@link android.support.v4.view.MotionEventCompat#getActionIndex getActionIndex()} to return the index of
+the pointer associated with the action. This is illustrated in the snippet below.</p>
+
+<p class="note"><strong>Note:</strong> This example uses the
+{@link android.support.v4.view.MotionEventCompat}
+class. This class is in the
+<a href="{@docRoot}tools/extras/support-library.html">Support Library</a>. You should use
+{@link android.support.v4.view.MotionEventCompat} to provide the best support for a wide range of
+platforms. Note that {@link android.support.v4.view.MotionEventCompat} is <em>not</em> a
+replacement for the {@link android.view.MotionEvent} class. Rather, it provides static utility
+methods to which you pass your {@link android.view.MotionEvent} object in order to receive
+the desired action associated with that event.</p>
+
+<pre>int action = MotionEventCompat.getActionMasked(event);
+// Get the index of the pointer associated with the action.
+int index = MotionEventCompat.getActionIndex(event);
+int xPos = -1;
+int yPos = -1;
+
+Log.d(DEBUG_TAG,"The action is " + actionToString(action));
+
+if (event.getPointerCount() > 1) {
+ Log.d(DEBUG_TAG,"Multitouch event");
+ // The coordinates of the current screen contact, relative to
+ // the responding View or Activity.
+ xPos = (int)MotionEventCompat.getX(event, index);
+ yPos = (int)MotionEventCompat.getY(event, index);
+
+} else {
+ // Single touch event
+ Log.d(DEBUG_TAG,"Single touch event");
+ xPos = (int)MotionEventCompat.getX(event, index);
+ yPos = (int)MotionEventCompat.getY(event, index);
+}
+...
+
+// Given an action int, returns a string description
+public static String actionToString(int action) {
+ switch (action) {
+
+ case MotionEvent.ACTION_DOWN: return "Down";
+ case MotionEvent.ACTION_MOVE: return "Move";
+ case MotionEvent.ACTION_POINTER_DOWN: return "Pointer Down";
+ case MotionEvent.ACTION_UP: return "Up";
+ case MotionEvent.ACTION_POINTER_UP: return "Pointer Up";
+ case MotionEvent.ACTION_OUTSIDE: return "Outside";
+ case MotionEvent.ACTION_CANCEL: return "Cancel";
+ }
+ return "";
+}</pre>
+
+
+
+
+<p>For more discussion of multi-touch and some examples, see the lesson <a href="scale.html">Dragging and Scaling</a>.
diff --git a/docs/html/training/gestures/scale.jd b/docs/html/training/gestures/scale.jd
new file mode 100644
index 0000000..17e4085
--- /dev/null
+++ b/docs/html/training/gestures/scale.jd
@@ -0,0 +1,240 @@
+page.title=Dragging and Scaling
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Managing Touch Events in a ViewGroup
+next.link=viewgroup.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#drag">Drag an Object</a></li>
+ <li><a href="#scale">Use Touch to Perform Scaling</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+<p>This lesson describes how to use touch gestures to drag and scale on-screen
+objects, using {@link android.view.View#onTouchEvent onTouchEvent()} to intercept
+touch events. Here is the original <a
+href="http://code.google.com/p/android-touchexample/">source code</a>
+for the examples used in this lesson.
+</p>
+
+<h2 id="drag">Drag an Object</h2>
+
+<p class="note">If you are targeting Android 3.0 or higher, you can use the built-in drag-and-drop event
+listeners with {@link android.view.View.OnDragListener}, as described in
+<a href="{@docRoot}guide/topics/ui/drag-drop.html">Drag and Drop</a>.
+
+<p>A common operation for a touch gesture is to use it to drag an object across
+the screen. The following snippet lets the user drag an on-screen image. Note
+the following:</p>
+
+<ul>
+
+<li>In a drag (or scroll) operation, the app has to keep track of the original pointer
+(finger), even if additional fingers get placed on the screen. For example,
+imagine that while dragging the image around, the user places a second finger on
+the touch screen and lifts the first finger. If your app is just tracking
+individual pointers, it will regard the second pointer as the default and move
+the image to that location.</li>
+
+<li>To prevent this from happening, your app needs to distinguish between the
+original pointer and any follow-on pointers. To do this, it tracks the
+{@link android.view.MotionEvent#ACTION_POINTER_DOWN} and
+{@link android.view.MotionEvent#ACTION_POINTER_UP} events described in
+<a href="multi.html">Handling Multi-Touch Gestures</a>.
+{@link android.view.MotionEvent#ACTION_POINTER_DOWN} and
+{@link android.view.MotionEvent#ACTION_POINTER_UP} are
+passed to the {@link android.view.View#onTouchEvent onTouchEvent()} callback
+whenever a secondary pointer goes down or up. </li>
+
+
+<li>In the {@link android.view.MotionEvent#ACTION_POINTER_UP} case, the example
+extracts this index and ensures that the active pointer ID is not referring to a
+pointer that is no longer touching the screen. If it is, the app selects a
+different pointer to be active and saves its current X and Y position. Since
+this saved position is used in the {@link android.view.MotionEvent#ACTION_MOVE}
+case to calculate the distance to move the onscreen object, the app will always
+calculate the distance to move using data from the correct pointer.</li>
+
+</ul>
+
+<p>The following snippet enables a user to drag an object around on the screen. It records the initial
+position of the active pointer, calculates the distance the pointer traveled, and moves the object to the
+new position. It correctly manages the possibility of additional pointers, as described
+above.</p>
+
+<p>Notice that the snippet uses the {@link android.view.MotionEvent#getActionMasked getActionMasked()} method.
+You should always use this method (or better yet, the compatability version
+{@link android.support.v4.view.MotionEventCompat#getActionMasked MotionEventCompat.getActionMasked()})
+to retrieve the action of a
+{@link android.view.MotionEvent}. Unlike the older
+{@link android.view.MotionEvent#getAction getAction()}
+method, {@link android.support.v4.view.MotionEventCompat#getActionMasked getActionMasked()}
+is designed to work with multiple pointers. It returns the masked action
+being performed, without including the pointer index bits.</p>
+
+<pre>// The ‘active pointer’ is the one currently moving our object.
+private int mActivePointerId = INVALID_POINTER_ID;
+
+@Override
+public boolean onTouchEvent(MotionEvent ev) {
+ // Let the ScaleGestureDetector inspect all events.
+ mScaleDetector.onTouchEvent(ev);
+
+ final int action = MotionEventCompat.getActionMasked(ev);
+
+ switch (action) {
+ case MotionEvent.ACTION_DOWN: {
+ final int pointerIndex = MotionEventCompat.getActionIndex(ev);
+ final float x = MotionEventCompat.getX(ev, pointerIndex);
+ final float y = MotionEventCompat.getY(ev, pointerIndex);
+
+ // Remember where we started (for dragging)
+ mLastTouchX = x;
+ mLastTouchY = y;
+ // Save the ID of this pointer (for dragging)
+ mActivePointerId = MotionEventCompat.getPointerId(ev, 0);
+ break;
+ }
+
+ case MotionEvent.ACTION_MOVE: {
+ // Find the index of the active pointer and fetch its position
+ final int pointerIndex =
+ MotionEventCompat.findPointerIndex(ev, mActivePointerId);
+
+ final float x = MotionEventCompat.getX(ev, pointerIndex);
+ final float y = MotionEventCompat.getY(ev, pointerIndex);
+
+ // Only move if the ScaleGestureDetector isn't processing a gesture.
+ if (!mScaleDetector.isInProgress()) {
+ // Calculate the distance moved
+ final float dx = x - mLastTouchX;
+ final float dy = y - mLastTouchY;
+
+ mPosX += dx;
+ mPosY += dy;
+
+ invalidate();
+ }
+ // Remember this touch position for the next move event
+ mLastTouchX = x;
+ mLastTouchY = y;
+
+ break;
+ }
+
+ case MotionEvent.ACTION_UP: {
+ mActivePointerId = INVALID_POINTER_ID;
+ break;
+ }
+
+ case MotionEvent.ACTION_CANCEL: {
+ mActivePointerId = INVALID_POINTER_ID;
+ break;
+ }
+
+ case MotionEvent.ACTION_POINTER_UP: {
+
+ final int pointerIndex = MotionEventCompat.getActionIndex(ev);
+ final int pointerId = MotionEventCompat.getPointerId(ev, pointerIndex);
+
+ if (pointerId == mActivePointerId) {
+ // This was our active pointer going up. Choose a new
+ // active pointer and adjust accordingly.
+ final int newPointerIndex = pointerIndex == 0 ? 1 : 0;
+ mLastTouchX = MotionEventCompat.getX(ev, newPointerIndex);
+ mLastTouchY = MotionEventCompat.getY(ev, newPointerIndex);
+ mActivePointerId = MotionEventCompat.getPointerId(ev, newPointerIndex);
+ }
+ break;
+ }
+ }
+ return true;
+}</pre>
+
+<h2 id="scale">Use Touch to Perform Scaling</h2>
+
+<p>As discussed in <a href="detector.html">Detecting Common Gestures</a>,
+{@link android.view.GestureDetector} helps you detect common gestures used by
+Android such as scrolling, flinging, and long press. For scaling, Android
+provides {@link android.view.ScaleGestureDetector}. {@link
+android.view.GestureDetector} and {@link android.view.ScaleGestureDetector} can
+be used together when you want a view to recognize additional gestures.</p>
+
+<p>To report detected gesture events, gesture detectors use listener objects
+passed to their constructors. {@link android.view.ScaleGestureDetector} uses
+{@link android.view.ScaleGestureDetector.OnScaleGestureListener}.
+Android provides
+{@link android.view.ScaleGestureDetector.SimpleOnScaleGestureListener}
+as a helper class that you can extend if you don’t care about all of the reported events.</p>
+
+<p>Here is a snippet that gives you the basic idea of how to perform scaling.
+Here is the original <a
+href="http://code.google.com/p/android-touchexample/">source code</a>
+for the examples.</p>
+
+<pre>private ScaleGestureDetector mScaleDetector;
+private float mScaleFactor = 1.f;
+
+public MyCustomView(Context mContext){
+ ...
+ // View code goes here
+ ...
+ mScaleDetector = new ScaleGestureDetector(context, new ScaleListener());
+}
+
+@Override
+public boolean onTouchEvent(MotionEvent ev) {
+ // Let the ScaleGestureDetector inspect all events.
+ mScaleDetector.onTouchEvent(ev);
+ return true;
+}
+
+@Override
+public void onDraw(Canvas canvas) {
+ super.onDraw(canvas);
+
+ canvas.save();
+ canvas.scale(mScaleFactor, mScaleFactor);
+ ...
+ // onDraw() code goes here
+ ...
+ canvas.restore();
+}
+
+private class ScaleListener
+ extends ScaleGestureDetector.SimpleOnScaleGestureListener {
+ @Override
+ public boolean onScale(ScaleGestureDetector detector) {
+ mScaleFactor *= detector.getScaleFactor();
+
+ // Don't let the object get too small or too large.
+ mScaleFactor = Math.max(0.1f, Math.min(mScaleFactor, 5.0f));
+
+ invalidate();
+ return true;
+ }
+}</pre>
diff --git a/docs/html/training/gestures/scroll.jd b/docs/html/training/gestures/scroll.jd
new file mode 100644
index 0000000..955495a
--- /dev/null
+++ b/docs/html/training/gestures/scroll.jd
@@ -0,0 +1,161 @@
+page.title=Animating a Scroll Gesture
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=Handling Multi-Touch Gestures
+next.link=multi.html
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#scroll">Implement Touch-Based Scrolling</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>In Android, scrolling is typically achieved by using the
+{@link android.widget.ScrollView}
+class. Any standard layout that might extend beyond the bounds of its container should be
+nested in a {@link android.widget.ScrollView} to provide a scrollable view that's
+managed by the framework. Implementing a custom scroller should only be
+necessary for special scenarios. This lesson describes such a scenario: displaying
+a scrolling effect in response to touch gestures using <em>scrollers</em>.
+
+
+<p>You can use scrollers ({@link android.widget.Scroller} or {@link
+android.widget.OverScroller}) to collect the data you need to produce a
+scrolling animation in response to a touch event. {@link
+android.widget.Scroller} and {@link android.widget.OverScroller} are largely
+interchangeable—the difference is that {@link android.widget.OverScroller}
+allows temporarily scrolling beyond the minimum/maximum boundaries and springing
+back to the bounds. This is normally rendered using a "glow" effect, provided by
+the {@link android.widget.EdgeEffect} or {@link
+android.support.v4.widget.EdgeEffectCompat} classes. </p>
+
+<p>A scroller is used to animate scrolling over time, using platform-standard
+scrolling physics (friction, velocity, etc.). The scroller itself doesn't
+actually draw anything. Scrollers track scroll offsets for you over time, but
+they don't automatically apply those positions to your view. It's your
+responsibility to get and apply new coordinates at a rate that will make the
+scrolling animation look smooth.</p>
+
+<p class="note"><strong>Note:</strong> You generally only need to use scrollers
+when implementing scrolling yourself. {@link android.widget.ScrollView} and
+{@link android.widget.HorizontalScrollView} do all this for you do all of this for you if you nest your layout within them.</p>
+
+<h2 id = "scroll">Implement Touch-Based Scrolling</h2>
+
+
+<p>This snippet illustrates the basics of using a scroller. It uses a
+{@link android.view.GestureDetector}, and overrides the
+{@link android.view.GestureDetector.SimpleOnGestureListener} methods
+{@link android.view.GestureDetector.OnGestureListener#onDown onDown()} and
+{@link android.view.GestureDetector.OnGestureListener#onFling onFling()}. It also
+overrides {@link android.view.GestureDetector.OnGestureListener#onScroll onScroll()}
+to return {@code false} since you don't need to animate a scroll.</p>
+
+
+<p>It's common to use scrollers in conjunction with a fling gesture, but they
+can be used in pretty much any context where you want the UI to display
+scrolling in response to a touch event. For example, you could override {@link
+android.view.View#onTouchEvent onTouchEvent()} to process touch events directly,
+and produce a scrolling effect in response to those touch events.</p>
+
+<pre>
+private OverScroller mScroller = new OverScroller(context);
+
+private GestureDetector.SimpleOnGestureListener mGestureListener
+ = new GestureDetector.SimpleOnGestureListener() {
+ @Override
+ public boolean onDown(MotionEvent e) {
+ // Abort any active scroll animations and invalidate.
+ mScroller.forceFinished(true);
+ // There is also a compatibility version:
+ // ViewCompat.postInvalidateOnAnimation
+ postInvalidateOnAnimation();
+ return true;
+ }
+
+ @Override
+ public boolean onScroll(MotionEvent e1, MotionEvent e2,
+ float distanceX, float distanceY) {
+ // You don't use a scroller in onScroll because you don't need to animate
+ // a scroll. The scroll occurs instantly in response to touch feedback.
+ return false;
+ }
+
+ @Override
+ public boolean onFling(MotionEvent e1, MotionEvent e2,
+ float velocityX, float velocityY) {
+ // Before flinging, abort the current animation.
+ mScroller.forceFinished(true);
+ // Begin the scroll animation
+ mScroller.fling(
+ // Current scroll position
+ startX,
+ startY,
+ // Velocities, negated for natural touch response
+ (int) -velocityX,
+ (int) -velocityY,
+ // Minimum and maximum scroll positions. The minimum scroll
+ // position is generally zero and the maximum scroll position
+ // is generally the content size less the screen size. So if the
+ // content width is 1000 pixels and the screen width is 200
+ // pixels, the maximum scroll offset should be 800 pixels.
+ minX, maxX,
+ minY, maxY,
+ // The maximum overscroll bounds. This is useful when using
+ // the EdgeEffect class to draw overscroll "glow" overlays.
+ mContentRect.width() / 2,
+ mContentRect.height() / 2);
+ // Invalidate to trigger computeScroll()
+ postInvalidateOnAnimation();
+ return true;
+ }
+};
+
+@Override
+public void computeScroll() {
+ super.computeScroll();
+
+ // Compute the current scroll offsets. If this returns true, then the
+ // scroll has not yet finished.
+ if (mScroller.computeScrollOffset()) {
+ int currX = mScroller.getCurrX();
+ int currY = mScroller.getCurrY();
+
+ // Actually render the scrolled viewport, or actually scroll the
+ // view using View.scrollTo.
+
+ // If currX or currY are outside the bounds, render the overscroll
+ // glow using EdgeEffect.
+
+ } else {
+ // The scroll has finished.
+ }
+}</pre>
+
+<p>For another example of scroller usage, see the <a href="http://github.com/android/platform_frameworks_support/blob/master/v4/java/android/support/v4/view/ViewPager.java">source code</a> for the
+{@link android.support.v4.view.ViewPager} class. It scrolls in response to flings,
+and uses scrolling to implement the "snapping to page" animation.</p>
diff --git a/docs/html/training/gestures/viewgroup.jd b/docs/html/training/gestures/viewgroup.jd
new file mode 100644
index 0000000..257a5d8
--- /dev/null
+++ b/docs/html/training/gestures/viewgroup.jd
@@ -0,0 +1,302 @@
+page.title=Managing Touch Events in a ViewGroup
+parent.title=Using Touch Gestures
+parent.link=index.html
+
+trainingnavtop=true
+next.title=
+next.link=
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#intercept">Intercept Touch Events in a ViewGroup</a></li>
+ <li><a href="#vc">Use ViewConfiguration Constants</a></li>
+ <li><a href="#delegate">Extend a Child View's Touchable Area</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+
+<ul>
+ <li><a href="http://developer.android.com/guide/topics/ui/ui-events.html">Input Events</a> API Guide
+ </li>
+ <li><a href="{@docRoot}guide/topics/sensors/sensors_overview.html">Sensors Overview</a></li>
+ <li><a href="http://android-developers.blogspot.com/2010/06/making-sense-of-multitouch.html">Making Sense of Multitouch</a> blog post</li>
+ <li><a href="{@docRoot}training/custom-views/making-interactive.html">Making the View Interactive</a> </li>
+ <li>Design Guide for <a href="{@docRoot}design/patterns/gestures.html">Gestures</a></li>
+ <li>Design Guide for <a href="{@docRoot}design/style/touch-feedback.html">Touch Feedback</a></li>
+</ul>
+
+
+</div>
+</div>
+
+<p>Handling touch events in a {@link android.view.ViewGroup} takes special care,
+because it's common for a {@link android.view.ViewGroup} to have children that
+are targets for different touch events than the {@link android.view.ViewGroup}
+itself. To make sure that each view correctly receives the touch events intended
+for it, override the {@link android.view.ViewGroup#onInterceptTouchEvent
+onInterceptTouchEvent()} method.</p>
+
+<h2 id="intercept">Intercept Touch Events in a ViewGroup</h2>
+
+<p>The {@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()}
+method is called whenever a touch event is detected on the surface of a
+{@link android.view.ViewGroup}, including on the surface of its children. If
+{@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()}
+returns {@code true}, the {@link android.view.MotionEvent} is intercepted,
+meaning it will be not be passed on to the child, but rather to the
+{@link android.view.View#onTouchEvent onTouchEvent()} method of the parent.</p>
+
+<p>The {@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()}
+method gives a parent the chance to see any touch event before its children do.
+If you return {@code true} from
+{@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()},
+the child view that was previously handling touch events
+receives an {@link android.view.MotionEvent#ACTION_CANCEL}, and the events from that
+point forward are sent to the parent's
+{@link android.view.View#onTouchEvent onTouchEvent()} method for the usual handling.
+{@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()} can also
+return {@code false} and simply spy on events as they travel down the view hierarchy
+to their usual targets, which will handle the events with their own
+{@link android.view.View#onTouchEvent onTouchEvent()}.
+
+
+<p>In the following snippet, the class {@code MyViewGroup} extends
+{@link android.view.ViewGroup}.
+{@code MyViewGroup} contains multiple child views. If you drag your finger across
+a child view horizontally, the child view should no longer get touch events, and
+{@code MyViewGroup} should handle touch events by scrolling its contents. However,
+if you press buttons in the child view, or scroll the child view vertically,
+the parent shouldn't intercept those touch events, because the child is the
+intended target. In those cases,
+{@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()} should
+return {@code false}, and {@code MyViewGroup}'s
+{@link android.view.View#onTouchEvent onTouchEvent()} won't be called.</p>
+
+<pre>public class MyViewGroup extends ViewGroup {
+
+ private int mTouchSlop;
+
+ ...
+
+ ViewConfiguration vc = ViewConfiguration.get(view.getContext());
+ mTouchSlop = vc.getScaledTouchSlop();
+
+ ...
+
+ @Override
+ public boolean onInterceptTouchEvent(MotionEvent ev) {
+ /*
+ * This method JUST determines whether we want to intercept the motion.
+ * If we return true, onTouchEvent will be called and we do the actual
+ * scrolling there.
+ */
+
+
+ final int action = MotionEventCompat.getActionMasked(ev);
+
+ // Always handle the case of the touch gesture being complete.
+ if (action == MotionEvent.ACTION_CANCEL || action == MotionEvent.ACTION_UP) {
+ // Release the scroll.
+ mIsScrolling = false;
+ return false; // Do not intercept touch event, let the child handle it
+ }
+
+ switch (action) {
+ case MotionEvent.ACTION_MOVE: {
+ if (mIsScrolling) {
+ // We're currently scrolling, so yes, intercept the
+ // touch event!
+ return true;
+ }
+
+ // If the user has dragged her finger horizontally more than
+ // the touch slop, start the scroll
+
+ // left as an exercise for the reader
+ final int xDiff = calculateDistanceX(ev);
+
+ // Touch slop should be calculated using ViewConfiguration
+ // constants.
+ if (xDiff > mTouchSlop) {
+ // Start scrolling!
+ mIsScrolling = true;
+ return true;
+ }
+ break;
+ }
+ ...
+ }
+
+ // In general, we don't want to intercept touch events. They should be
+ // handled by the child view.
+ return false;
+ }
+
+ @Override
+ public boolean onTouchEvent(MotionEvent ev) {
+ // Here we actually handle the touch event (e.g. if the action is ACTION_MOVE,
+ // scroll this container).
+ // This method will only be called if the touch event was intercepted in
+ // onInterceptTouchEvent
+ ...
+ }
+}</pre>
+
+<p>Note that {@link android.view.ViewGroup} also provides a
+{@link android.view.ViewGroup#requestDisallowInterceptTouchEvent requestDisallowInterceptTouchEvent()} method.
+The {@link android.view.ViewGroup} calls this method when a child does not want the parent and its
+ancestors to intercept touch events with
+{@link android.view.ViewGroup#onInterceptTouchEvent onInterceptTouchEvent()}.
+</p>
+
+<h2 id="vc">Use ViewConfiguration Constants</h2>
+
+<p>The above snippet uses the current {@link android.view.ViewConfiguration} to initialize
+a variable called {@code mTouchSlop}. You can use the {@link
+android.view.ViewConfiguration} class to access common distances, speeds, and
+times used by the Android system.</p>
+
+
+<p>"Touch slop" refers to the distance in pixels a user's touch can wander
+before the gesture is interpreted as scrolling. Touch slop is typically used to
+prevent accidental scrolling when the user is performing some other touch
+operation, such as touching on-screen elements.</p>
+
+<p>Two other commonly used {@link android.view.ViewConfiguration} methods are
+{@link android.view.ViewConfiguration#getScaledMinimumFlingVelocity getScaledMinimumFlingVelocity()}
+and {@link android.view.ViewConfiguration#getScaledMaximumFlingVelocity getScaledMaximumFlingVelocity()}.
+These methods return the minimum and maximum velocity (respectively) to initiate a fling,
+as measured in pixels per second. For example:</p>
+
+<pre>ViewConfiguration vc = ViewConfiguration.get(view.getContext());
+private int mSlop = vc.getScaledTouchSlop();
+private int mMinFlingVelocity = vc.getScaledMinimumFlingVelocity();
+private int mMaxFlingVelocity = vc.getScaledMaximumFlingVelocity();
+
+...
+
+case MotionEvent.ACTION_MOVE: {
+ ...
+ float deltaX = motionEvent.getRawX() - mDownX;
+ if (Math.abs(deltaX) > mSlop) {
+ // A swipe occurred, do something
+ }
+
+...
+
+case MotionEvent.ACTION_UP: {
+ ...
+ } if (mMinFlingVelocity <= velocityX && velocityX <= mMaxFlingVelocity
+ && velocityY < velocityX) {
+ // The criteria have been satisfied, do something
+ }
+}</pre>
+
+
+<h2 id="delegate">Extend a Child View's Touchable Area</h2>
+
+<p>Android provides the {@link android.view.TouchDelegate} class to make it possible
+for a parent to extend the touchable area of a child view beyond the child's bounds.
+
+This is useful when the child has to be small, but should have a larger touch region. You can
+also use this approach to shrink the child's touch region if need be.</p>
+
+<p>In the following example, an {@link android.widget.ImageButton} is the
+"delegate view" (that is, the child whose touch area the parent will extend).
+Here is the layout file:</p>
+
+<pre>
+<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+ android:id="@+id/parent_layout"
+ android:layout_width="match_parent"
+ android:layout_height="match_parent"
+ tools:context=".MainActivity" >
+
+ <ImageButton android:id="@+id/button"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:background="@null"
+ android:src="@drawable/icon" />
+</RelativeLayout>
+</pre>
+
+<p>The snippet below does the following:</p>
+
+<ul>
+<li>Gets the parent view and posts a {@link java.lang.Runnable} on the UI thread. This ensures that the parent lays out its children before calling the {@link android.view.View#getHitRect getHitRect()} method. The {@link android.view.View#getHitRect getHitRect()} method gets the child's hit rectangle (touchable area) in the parent's coordinates.</li>
+<li>Finds the {@link android.widget.ImageButton} child view and calls {@link android.view.View#getHitRect getHitRect()} to get the bounds of the child's touchable area.</li>
+<li>Extends the bounds of the {@link android.widget.ImageButton}'s hit rectangle.</li>
+<li>Instantiates a {@link android.view.TouchDelegate}, passing in the expanded hit rectangle and the {@link android.widget.ImageButton} child view as parameters.</li>
+<li>Sets the {@link android.view.TouchDelegate} on the parent view, such that touches within the touch delegate bounds are routed to the child.</li>
+
+</ul>
+
+In its capacity as touch delegate for the {@link android.widget.ImageButton} child view, the
+parent view will receive all touch events. If the touch event occurred within the child's hit
+rectangle, the parent will pass the touch
+event to the child for handling.</p>
+
+
+
+<pre>
+public class MainActivity extends Activity {
+
+ @Override
+ protected void onCreate(Bundle savedInstanceState) {
+ super.onCreate(savedInstanceState);
+ setContentView(R.layout.activity_main);
+ // Get the parent view
+ View parentView = findViewById(R.id.parent_layout);
+
+ parentView.post(new Runnable() {
+ // Post in the parent's message queue to make sure the parent
+ // lays out its children before you call getHitRect()
+ @Override
+ public void run() {
+ // The bounds for the delegate view (an ImageButton
+ // in this example)
+ Rect delegateArea = new Rect();
+ ImageButton myButton = (ImageButton) findViewById(R.id.button);
+ myButton.setEnabled(true);
+ myButton.setOnClickListener(new View.OnClickListener() {
+ @Override
+ public void onClick(View view) {
+ Toast.makeText(MainActivity.this,
+ "Touch occurred within ImageButton touch region.",
+ Toast.LENGTH_SHORT).show();
+ }
+ });
+
+ // The hit rectangle for the ImageButton
+ myButton.getHitRect(delegateArea);
+
+ // Extend the touch area of the ImageButton beyond its bounds
+ // on the right and bottom.
+ delegateArea.right += 100;
+ delegateArea.bottom += 100;
+
+ // Instantiate a TouchDelegate.
+ // "delegateArea" is the bounds in local coordinates of
+ // the containing view to be mapped to the delegate view.
+ // "myButton" is the child view that should receive motion
+ // events.
+ TouchDelegate touchDelegate = new TouchDelegate(delegateArea,
+ myButton);
+
+ // Sets the TouchDelegate on the parent view, such that touches
+ // within the touch delegate bounds are routed to the child.
+ if (View.class.isInstance(myButton.getParent())) {
+ ((View) myButton.getParent()).setTouchDelegate(touchDelegate);
+ }
+ }
+ });
+ }
+}</pre>
+
diff --git a/docs/html/training/improving-layouts/reusing-layouts.jd b/docs/html/training/improving-layouts/reusing-layouts.jd
index fdd3333..87431d3 100644
--- a/docs/html/training/improving-layouts/reusing-layouts.jd
+++ b/docs/html/training/improving-layouts/reusing-layouts.jd
@@ -109,6 +109,10 @@
layout=”@layout/title”/>
</pre>
+<p>However, if you want to override layout attributes using
+the <code><include></code> tag, you must override both
+<code>android:layout_height</code> and <code>android:layout_width</code> in order for
+other layout attributes to take effect.</p>
<h2 id="Merge">Use the <merge> Tag</h2>
diff --git a/docs/html/training/keyboard-input/commands.jd b/docs/html/training/keyboard-input/commands.jd
new file mode 100644
index 0000000..9d2de41
--- /dev/null
+++ b/docs/html/training/keyboard-input/commands.jd
@@ -0,0 +1,113 @@
+page.title=Handling Keyboard Actions
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#SingleKey">Handle Single Key Events</a></li>
+ <li><a href="#ModifierKey">Handle Modifier Keys</a></li>
+</ol>
+
+</div>
+</div>
+
+
+<p>When the user gives focus to an editable text view such as an {@link android.widget.EditText}
+element and the user has a hardware keyboard attached, all
+input is handled by the system. If, however, you'd like to intercept
+or directly handle the keyboard input yourself, you can do so by implementing callback methods
+from the {@link android.view.KeyEvent.Callback} interface, such as {@link
+android.view.KeyEvent.Callback#onKeyDown onKeyDown()} and {@link
+android.view.KeyEvent.Callback#onKeyMultiple onKeyMultiple()}.</p>
+
+<p>Both the {@link
+android.app.Activity} and {@link android.view.View} class implement the
+{@link android.view.KeyEvent.Callback} interface, so you
+should generally override the callback methods in your extension of these classes as
+appropriate.</p>
+
+<p class="note"><strong>Note:</strong> When handling keyboard events with the {@link
+android.view.KeyEvent} class and related APIs, you should expect that such keyboard
+events come only from a hardware keyboard. You should never rely on receiving key events
+for any key on a soft input method (an on-screen keyboard).</p>
+
+
+<h2 id="SingleKey">Handle Single Key Events</h2>
+
+<p>To handle an individual key press, implement {@link
+android.app.Activity#onKeyDown onKeyDown()} or {@link
+android.app.Activity#onKeyUp onKeyUp()} as appropriate. Usually, you should
+use {@link android.app.Activity#onKeyUp onKeyUp()} if you want to be sure that you receive
+only one event. If the user presses and holds the button, then {@link
+android.app.Activity#onKeyDown onKeyDown()} is called multiple times.</p>
+
+<p>For example, this implementation responds to some keyboard keys to control a game:</p>
+
+<pre>
+@Override
+public boolean onKeyUp(int keyCode, KeyEvent event) {
+ switch (keyCode) {
+ case KeyEvent.KEYCODE_D:
+ moveShip(MOVE_LEFT);
+ return true;
+ case KeyEvent.KEYCODE_F:
+ moveShip(MOVE_RIGHT);
+ return true;
+ case KeyEvent.KEYCODE_J:
+ fireMachineGun();
+ return true;
+ case KeyEvent.KEYCODE_K:
+ fireMissile();
+ return true;
+ default:
+ return super.onKeyUp(keyCode, event);
+ }
+}
+</pre>
+
+
+<h2 id="ModifierKey">Handle Modifier Keys</h2>
+
+<p>To respond to modifier key events such as when a key is combined with Shift or Control, you can
+query the {@link android.view.KeyEvent} that's passed to the callback method. Several methods
+provide information about modifier keys such as {@link android.view.KeyEvent#getModifiers()}
+and {@link android.view.KeyEvent#getMetaState()}. However, the simplest solution is to check whether
+the exact modifier key you care about is being pressed with methods such as
+{@link android.view.KeyEvent#isShiftPressed()} and {@link android.view.KeyEvent#isCtrlPressed()}.
+</p>
+
+<p>For example, here's the {@link android.app.Activity#onKeyDown onKeyDown()} implementation
+again, with some extra handling for when the Shift key is held down with one of the keys:</p>
+
+<pre>
+@Override
+public boolean onKeyUp(int keyCode, KeyEvent event) {
+ switch (keyCode) {
+ ...
+ case KeyEvent.KEYCODE_J:
+ if (event.isShiftPressed()) {
+ fireLaser();
+ } else {
+ fireMachineGun();
+ }
+ return true;
+ case KeyEvent.KEYCODE_K:
+ if (event.isShiftPressed()) {
+ fireSeekingMissle();
+ } else {
+ fireMissile();
+ }
+ return true;
+ default:
+ return super.onKeyUp(keyCode, event);
+ }
+}
+</pre>
+
+
+
diff --git a/docs/html/training/keyboard-input/index.jd b/docs/html/training/keyboard-input/index.jd
new file mode 100644
index 0000000..ba4e598
--- /dev/null
+++ b/docs/html/training/keyboard-input/index.jd
@@ -0,0 +1,54 @@
+page.title=Handling Keyboard Input
+
+trainingnavtop=true
+startpage=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+<ul>
+ <li>Android 1.6 (API Level 3) or higher</li>
+</ul>
+
+</div>
+</div>
+
+<p>The Android system shows an on-screen keyboard—known as a
+<em>soft input method</em>—when a text field in your UI receives focus.
+To provide the best user experience, you can specify characteristics
+about the type of input you expect (such as
+whether it's a phone number or email address) and how the input method should behave (such as
+whether it performs auto-correct for spelling mistakes).</p>
+
+<p>In addition to the on-screen input methods, Android also supports hardware keyboards, so it's
+important that your app optimize its user experience for interaction that might occur
+through an attached keyboard.</p>
+
+<p>These topics and more are discussed in the following lessons.</p>
+
+
+<h2>Lessons</h2>
+
+<dl>
+ <dt><b><a href="style.html">Specifying the Input Method Type</a></b></dt>
+ <dd>Learn how to show certain soft input methods, such as those designed for phone numbers, web
+ addresses, or other formats. Also learn how to specify characteristics such
+ as spelling suggestion behavior and action buttons such as <b>Done</b> or <b>Next</b>.
+ </dd>
+ <dt><b><a href="visibility.html">Handling Input Method Visibility</a></b></dt>
+ <dd>Learn how to specify when to show the soft input method and how
+ your layout should adjust to the reduced screen space.
+ </dd>
+ <dt><b><a href="navigation.html">Supporting Keyboard Navigation</a></b></dt>
+ <dd>Learn how to verify that users can navigate your app using a keyboard
+ and how to make any necessary changes to the navigation order.
+ </dd>
+ <dt><b><a href="commands.html">Handling Keyboard Actions</a></b></dt>
+ <dd>Learn how to respond directly to keyboard input for user actions.
+ </dd>
+
+</dl>
\ No newline at end of file
diff --git a/docs/html/training/keyboard-input/navigation.jd b/docs/html/training/keyboard-input/navigation.jd
new file mode 100644
index 0000000..6e26ab2
--- /dev/null
+++ b/docs/html/training/keyboard-input/navigation.jd
Binary files differ
diff --git a/docs/html/training/keyboard-input/style.jd b/docs/html/training/keyboard-input/style.jd
new file mode 100644
index 0000000..b0e506c
--- /dev/null
+++ b/docs/html/training/keyboard-input/style.jd
@@ -0,0 +1,171 @@
+page.title=Specifying the Input Method Type
+
+trainingnavtop=true
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Type">Specify the Keyboard Type</a></li>
+ <li><a href="#Spelling">Enable Spelling Suggestions and Other Behaviors</a></li>
+ <li><a href="#Action">Specify the Input Method Action</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/topics/ui/controls/text.html">Text Fields</a></li>
+</ul>
+
+</div>
+</div>
+
+
+<p>Every text field expects a certain type of text input, such as an
+email address, phone number, or just plain text. So it's important
+that you specify the input type for each text field in your app
+so the system displays the appropriate soft input method (such as an on-screen keyboard).</p>
+
+<p>Beyond the type of buttons available with an input method, you should specify
+behaviors such as whether the input method provides spelling suggestions,
+capitalizes new sentences, and replaces the carriage return button with an
+action button such as a <b>Done</b> or <b>Next</b>.
+This lesson shows how to specify these characteristics.</p>
+
+
+
+<h2 id="Type">Specify the Keyboard Type</h2>
+
+<p>You should always declare the input method for your text fields by adding
+the <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute to the {@link android.widget.EditText
+<EditText>} element.</p>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/ui/edittext-phone.png" alt="" />
+<p class="img-caption"><strong>Figure 1.</strong> The {@code phone} input type.</p>
+</div>
+
+<p>For example, if you'd like an input method for entering a phone number,
+use the {@code "phone"} value:</p>
+<pre>
+<EditText
+ android:id="@+id/phone"
+ android:layout_width="fill_parent"
+ android:layout_height="wrap_content"
+ android:hint="@string/phone_hint"
+ android:inputType="phone" />
+</pre>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/training/input/ime_password.png" alt="" />
+<p class="img-caption"><strong>Figure 2.</strong> The {@code textPassword} input type.</p>
+</div>
+
+<p>Or if the text field is for a password, use the {@code "textPassword"} value
+so the text field conceals the user's input:</p>
+<pre>
+<EditText
+ android:id="@+id/password"
+ android:hint="@string/password_hint"
+ android:inputType="textPassword"
+ ... />
+</pre>
+
+<p>There are several possible values documented with the
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute and
+some of the values can be combined to specify the input method
+appearance and additional behaviors.</p>
+
+
+
+<h2 id="Spelling">Enable Spelling Suggestions and Other Behaviors</h2>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/training/input/ime_autocorrect.png" alt="" />
+<p class="img-caption"><strong>Figure 3.</strong> Adding {@code textAutoCorrect}
+provides auto-correction for misspellings.</p>
+</div>
+
+<p>The <a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute allows you to specify various behaviors for the
+input method. Most importantly, if your text field is intended for basic text input (such
+as for a text message), you should enable auto spelling correction with the
+{@code "textAutoCorrect"} value.</p>
+
+<p>You can combine different behaviors and input method styles with the
+<a href="{@docRoot}reference/android/widget/TextView.html#attr_android:inputType"
+>{@code android:inputType}</a> attribute. For example,
+here's how to create a text field that capitalizes the first word of a sentence
+and also auto-corrects misspellings:</p>
+
+<pre>
+<EditText
+ android:id="@+id/message"
+ android:layout_width="wrap_content"
+ android:layout_height="wrap_content"
+ android:inputType=
+ "textCapSentences|textAutoCorrect"
+ ... />
+</pre>
+
+
+
+
+<h2 id="Action">Specify the Input Method Action</h2>
+
+<p>Most soft input methods provide a user action button in the
+bottom corner that's appropriate for the current text field.
+By default, the system uses this button for either a <b>Next</b> or
+<b>Done</b> action unless your text field allows multi-line text (such as with {@code
+android:inputType="textMultiLine"}), in which case the action button is a carriage return.
+However, you can specify additional actions that might be more appropriate for your
+text field, such as <b>Send</b> or <b>Go</b>.</p>
+
+<p>To specify the keyboard action button, use the <a
+href="{@docRoot}reference/android/widget/TextView.html#attr_android:imeOptions">{@code
+android:imeOptions}</a> attribute with an action value such as {@code "actionSend"} or
+{@code "actionSearch"}. For example:</p>
+
+<div class="figure" style="width:300px">
+<img src="{@docRoot}images/ui/edittext-actionsend.png" alt="" />
+<p class="img-caption"><strong>Figure 4.</strong> The Send button appears when you declare
+{@code android:imeOptions="actionSend"}.</p>
+</div>
+
+<pre>
+<EditText
+ android:id="@+id/search"
+ android:layout_width="fill_parent"
+ android:layout_height="wrap_content"
+ android:hint="@string/search_hint"
+ android:inputType="text"
+ android:imeOptions="actionSend" />
+</pre>
+
+<p>You can then listen for presses on the action button by defining a
+{@link android.widget.TextView.OnEditorActionListener} for the {@link android.widget.EditText}
+element. In your listener, respond to the appropriate IME action ID defined in the
+{@link android.view.inputmethod.EditorInfo} class, such as
+{@link android.view.inputmethod.EditorInfo#IME_ACTION_SEND}. For example:</p>
+
+<pre>
+EditText editText = (EditText) findViewById(R.id.search);
+editText.setOnEditorActionListener(new OnEditorActionListener() {
+ @Override
+ public boolean onEditorAction(TextView v, int actionId, KeyEvent event) {
+ boolean handled = false;
+ if (actionId == EditorInfo.IME_ACTION_SEND) {
+ sendMessage();
+ handled = true;
+ }
+ return handled;
+ }
+});
+</pre>
+
+
+
diff --git a/docs/html/training/keyboard-input/visibility.jd b/docs/html/training/keyboard-input/visibility.jd
new file mode 100644
index 0000000..5dc6fc260
--- /dev/null
+++ b/docs/html/training/keyboard-input/visibility.jd
Binary files differ
diff --git a/docs/html/training/load-data-background/define-launch-query.jd b/docs/html/training/load-data-background/define-launch-query.jd
deleted file mode 100644
index f7978f4..0000000
--- a/docs/html/training/load-data-background/define-launch-query.jd
+++ /dev/null
@@ -1,83 +0,0 @@
-page.title=Defining and Launching the Query
-trainingnavtop=true
-startpage=true
-
-@jd:body
-
-<!-- This is the training bar -->
-<div id="tb-wrapper">
- <div id="tb">
-<h2>This lesson teaches you to</h2>
-<ol>
- <li>
- <a href="#DefineLaunch">Define and Launch the Query</a>
- </li>
-</ol>
- </div>
-</div>
-
-<p>
- To perform a query, create the {@link android.support.v4.content.CursorLoader}, set up its
- query, and pass it to the loader framework. From then on, the framework manages everything.
- It runs the query on a background thread, returns the results to the foreground, and
- watches for changes to the data associated with the query.
-</p>
-<p>
- Pass a {@link android.support.v4.content.CursorLoader} to the loader framework in
- your implementation of
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}.
- The loader framework calls this method when you <i>create</i> a loader by calling
- {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. You can create
- a {@link android.support.v4.content.CursorLoader} anywhere,
- but the preferred way is to create it in
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()},
- because this defers creation until the object is actually needed.
-</p>
-<p>
- Notice that {@link android.support.v4.app.LoaderManager#initLoader initLoader()} will only
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}
- if the {@link android.support.v4.content.CursorLoader} doesn't already exist; otherwise, it
- re-uses the existing {@link android.support.v4.content.CursorLoader}. The loader framework
- tracks {@link android.support.v4.content.CursorLoader} instance using the <code>id</code>
- value passed to {@link android.support.v4.app.LoaderManager#initLoader initLoader()}.
-</p>
-<h2 id="DefineLaunch">Define and Launch the Query</h2>
-<p>
- To create a {@link android.support.v4.content.CursorLoader} and define its
- query at the same time, call the constructor
-{@link android.support.v4.content.CursorLoader#CursorLoader(Context, Uri, String[], String, String[], String)
- CursorLoader(context, uri, projection, selection, selectionArgs, sortOrder)}. The
- <code>context</code> and <code>uri</code> arguments are required, but the others are optional.
- To use the default value for an optional argument, pass in <code>null</code>. The
- {@link android.support.v4.content.CursorLoader} runs the query against the
- {@link android.content.ContentProvider} identified by <code>uri</code>, just as if you had
- called {@link android.content.ContentResolver#query ContentResolver.query()} with the same
- arguments.
-</p>
-<p>
- For example:
-</p>
-<pre>
-public Loader<Cursor> onCreateLoader(int loaderID, Bundle bundle)
-{
- /*
- * Takes action based on the ID of the Loader that's being created
- */
- switch (loaderID) {
- case URL_LOADER:
- /*
- * Return a new CursorLoader
- */
- return new CursorLoader(
- this, // Context
- DataProviderContract.IMAGE_URI, // Provider's content URI
- PROJECTION, // Columns to return
- null, // Return all rows
- null, // No search arguments
- null); // Default search order
- default:
- // An invalid id was passed in
- return null;
- }
-}
-</pre>
diff --git a/docs/html/training/load-data-background/handle-results.jd b/docs/html/training/load-data-background/handle-results.jd
index f8e003a..ce0024f 100644
--- a/docs/html/training/load-data-background/handle-results.jd
+++ b/docs/html/training/load-data-background/handle-results.jd
@@ -13,92 +13,125 @@
<a href="#HandleResults">Handle Query Results</a>
</li>
<li>
- <a href="#HandleReset">Clear Out Old Data</a></li>
+ <a href="#HandleReset">Delete Old Cursor References</a></li>
</ol>
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
</div>
</div>
<p>
- {@link android.support.v4.content.CursorLoader} returns its query results to your
- implementation of
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished
- LoaderCallbacks.onLoadFinished()}, in the form of a {@link android.database.Cursor}. In the
- callback, you can update your data display, do further processing on the
- {@link android.database.Cursor} data, and so forth.
+ As shown in the previous lesson, you should begin loading your data with a
+ {@link android.support.v4.content.CursorLoader} in your implementation of
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader
+ onCreateLoader()}. The loader then provides the query results to your
+ {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity} in your
+ implementation of {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished
+ LoaderCallbacks.onLoadFinished()}. One of the incoming arguments to this method is a
+ {@link android.database.Cursor} containing the query results. You can use this object to
+ update your data display or do further processing.
</p>
<p>
- When the loader framework detects changes to data associated with the query,
- it resets the {@link android.support.v4.content.CursorLoader}, closes the current
- {@link android.database.Cursor}, and then invokes your implementation of
+ Besides
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()} and
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()},
+ you also have to implement
{@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}.
- Use this callback to delete references to the current {@link android.database.Cursor}; when the
- loader framework destroys the {@link android.database.Cursor}, you won't have outstanding
- references that cause memory leaks.
+ This method is invoked when {@link android.support.v4.content.CursorLoader} detects
+ that data associated with the {@link android.database.Cursor} has changed. When the
+ data changes, the framework also re-runs the current query.
</p>
-<h2 id="HandleFinished">Handle Query Results</h2>
+<h2 id="HandleResults">Handle Query Results</h2>
<p>
- The following two snippets are an example of displaying the results of a query, using a
- {@link android.widget.ListView} backed by a
- {@link android.support.v4.widget.SimpleCursorAdapter}.
+ To display {@link android.database.Cursor} data returned by
+ {@link android.support.v4.content.CursorLoader}, use a
+ {@link android.view.View} class that implements {@link android.widget.AdapterView} and
+ provide the view with an adapter that implements
+ {@link android.support.v4.widget.CursorAdapter}. The system then automatically moves data from
+ the {@link android.database.Cursor} to the view.
</p>
<p>
- The first snippet shows the {@link android.widget.ListView} and
- {@link android.support.v4.widget.SimpleCursorAdapter}:
-</p>
-<pre>
-// Gets a handle to the Android built-in ListView widget
-mListView = ((ListView) findViewById(android.R.id.list));
-// Creates a CursorAdapter
-mAdapter =
- new SimpleCursorAdapter(
- this, // Current context
- R.layout.logitem, // View for each item in the list
- null, // Don't provide the cursor yet
- FROM_COLUMNS, // List of cursor columns to display
- TO_FIELDS, // List of TextViews in each line
- 0 // flags
-);
-// Links the adapter to the ListView
-mListView.setAdapter(mAdapter);
-</pre>
-<p>
- The next snippet shows an implementation of
+ You can set up the linkage between the view and adapter before you have any data to display,
+ and then move a {@link android.database.Cursor} into the adapter in the
{@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()}
- that moves the query results in the returned {@link android.database.Cursor} to the
- {@link android.support.v4.widget.SimpleCursorAdapter}. Changing the
- {@link android.database.Cursor} in the
- {@link android.support.v4.widget.SimpleCursorAdapter} triggers a refresh of the
- {@link android.widget.ListView} with the new data:
-</p>
-<pre>
-public void onLoadFinished(Loader<Cursor> loader, Cursor cursor)
-{
- /*
- * Move the results into the adapter. This
- * triggers the ListView to re-display.
- */
- mAdapter.swapCursor(cursor);
-}
-</pre>
-<h2 id="HandleReset">Handle a Loader Reset</h2>
-<p>
- The loader framework resets the {@link android.support.v4.content.CursorLoader} whenever the
- {@link android.database.Cursor} becomes invalid. This usually occurs because the data associated
- with the {@link android.database.Cursor} has changed. Before re-running the query,
- the framework calls your implementation of
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}. In
- this callback, make sure to prevent memory leaks by deleting all references to the current
- {@link android.database.Cursor}. Once you return from
- {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()},
- the loader framework re-runs the query.
+ method. As soon as you move the {@link android.database.Cursor} into the adapter, the
+ system automatically updates the view. This also happens if you change the contents of the
+ {@link android.database.Cursor}.
</p>
<p>
For example:
</p>
<pre>
-public void onLoaderReset(Loader<Cursor> loader)
-{
- // Remove the reference to the current Cursor
- mAdapter.swapCursor(null);
+public String[] mFromColumns = {
+ DataProviderContract.IMAGE_PICTURENAME_COLUMN
+};
+public int[] mToFields = {
+ R.id.PictureName
+};
+// Gets a handle to a List View
+ListView mListView = (ListView) findViewById(R.id.dataList);
+/*
+ * Defines a SimpleCursorAdapter for the ListView
+ *
+ */
+SimpleCursorAdapter mAdapter =
+ new SimpleCursorAdapter(
+ this, // Current context
+ R.layout.list_item, // Layout for a single row
+ null, // No Cursor yet
+ mFromColumns, // Cursor columns to use
+ mToFields, // Layout fields to use
+ 0 // No flags
+ );
+// Sets the adapter for the view
+mListView.setAdapter(mAdapter);
+...
+/*
+ * Defines the callback that {@link android.support.v4.content.CursorLoader} calls
+ * when it's finished its query
+ */
+@Override
+public void onLoadFinished(Loader<Cursor> loader, Cursor cursor) {
+ ...
+ /*
+ * Moves the query results into the adapter, causing the
+ * ListView fronting this adapter to re-display
+ */
+ mAdapter.changeCursor(cursor);
+}
+</pre>
+<h2 id="HandleReset">Delete Old Cursor References</h2>
+<p>
+ The {@link android.support.v4.content.CursorLoader} is reset whenever its
+ {@link android.database.Cursor} becomes invalid. This usually occurs because the data associated
+ with the {@link android.database.Cursor} has changed. Before re-running the query,
+ the framework calls your implementation of
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}. In
+ this callback, you should delete all references to the current {@link android.database.Cursor}
+ in order to prevent memory leaks. Once
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoaderReset onLoaderReset()}
+ finishes, {@link android.support.v4.content.CursorLoader} re-runs its query.
+</p>
+<p>
+ For example:
+</p>
+<pre>
+/*
+ * Invoked when the CursorLoader is being reset. For example, this is
+ * called if the data in the provider changes and the Cursor becomes stale.
+ */
+@Override
+public void onLoaderReset(Loader<Cursor> loader) {
+
+ /*
+ * Clears out the adapter's reference to the Cursor.
+ * This prevents memory leaks.
+ */
+ mAdapter.changeCursor(null);
}
</pre>
diff --git a/docs/html/training/load-data-background/index.jd b/docs/html/training/load-data-background/index.jd
index 574a32c..dc9d84a 100644
--- a/docs/html/training/load-data-background/index.jd
+++ b/docs/html/training/load-data-background/index.jd
@@ -8,22 +8,11 @@
<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
<h2>Dependencies and prerequisites</h2>
-<h3>Dependencies</h3>
<ul>
<li>
Android 1.6 or later
</li>
</ul>
-<h3>Prerequisites</h3>
-<ul>
- <li>
- <a href="{@docRoot}training/basics/firstapp/index.html">Building Your First App</a> class
- </li>
- <li>
- <a href="{@docRoot}training/basics/activity-lifecycle/index.html">
- Managing the Activity Lifecycle</a> class
- </li>
-</ul>
<!-- related docs (NOT javadocs) -->
<h2>You should also read</h2>
@@ -38,71 +27,42 @@
<a href="{@docRoot}guide/topics/providers/content-provider-basics.html">Content Provider Basics</a>
</li>
</ul>
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
</div>
</div>
<p>
- A {@link android.support.v4.content.CursorLoader} runs a query against a
- {@link android.content.ContentProvider} on a background thread and returns a
- {@link android.database.Cursor} to the main thread.
+ Querying a {@link android.content.ContentProvider} for data you want to display takes time.
+ If you run the query directly from an {@link android.app.Activity}, it may get blocked and
+ cause the system to issue an "Application Not Responding" message. Even if it doesn't, users
+ will see an annoying delay in the UI. To avoid these problems, you should initiate a query on a
+ separate thread, wait for it to finish, and then display the results.
</p>
<p>
- {@link android.support.v4.content.CursorLoader} has these advantages over alternate ways of
- running a query:
-</p>
-<dl>
- <dt>
- Query on a background thread
- </dt>
- <dd>
- A {@link android.support.v4.content.CursorLoader} query runs asynchronously on a
- background thread, so it doesn't cause "Application Not Responding" (ANR) errors on the UI
- thread. {@link android.support.v4.content.CursorLoader} creates and starts the
- background thread; all you have to do is initialize the loader framework and handle the
- results of the query.
- </dd>
- <dt>
- Automatic re-query
- </dt>
- <dd>
- A {@link android.support.v4.content.CursorLoader} automatically runs a new query when
- the loader framework detects that the data underlying the {@link android.database.Cursor}
- has changed.
- </dd>
- <dt>
- Simple API
- </dt>
- <dd>
- The {@link android.support.v4.content.CursorLoader} API provides the
- query framework and cursor monitoring that you would have to define yourself if you used
- {@link android.os.AsyncTask}.
- </dd>
-</dl>
-<p>
- A {@link android.support.v4.content.CursorLoader} is limited in that the query must be
- against a {@link android.net.Uri} and must return a {@link android.database.Cursor}. Because of
- this, a {@link android.support.v4.content.CursorLoader} can only run a query against a
- {@link android.content.ContentProvider}.
+ You can do this in a straightforward way by using an object that runs a query asynchronously in
+ the background and reconnects to your {@link android.app.Activity} when it's finished. This
+ object is a {@link android.support.v4.content.CursorLoader}. Besides doing the initial
+ background query, a {@link android.support.v4.content.CursorLoader} automatically re-runs the
+ query when data associated with the query changes.
</p>
<p>
- This class describes how to define and use a {@link android.support.v4.content.CursorLoader}.
- Examples in this class use the {@link android.support.v4 v4 support library} versions of
- classes, which support platforms starting with Android 1.6.
+ This class describes how to use a {@link android.support.v4.content.CursorLoader} to run a
+ background query. Examples in this class use the {@link android.support.v4 v4 support library}
+ versions of classes, which support platforms starting with Android 1.6.
</p>
<h2>Lessons</h2>
<dl>
<dt>
- <strong><a href="setup-loader.html">Setting Up the Loader</a></strong>
+ <strong><a href="setup-loader.html">Running a Query with a CursorLoader</a></strong>
</dt>
<dd>
- Learn how to set up an {@link android.app.Activity} that inherits the necessary classes
- for running a {@link android.support.v4.content.CursorLoader} and returning results.
- </dd>
- <dt>
- <strong><a href="define-launch-query.html">Defining and Launching the Query</a></strong>
- </dt>
- <dd>
- Learn how to perform a query against a {@link android.content.ContentProvider} using
- a {@link android.support.v4.content.CursorLoader}.
+ Learn how to run a query in the background, using a
+ {@link android.support.v4.content.CursorLoader}.
</dd>
<dt>
<strong>
diff --git a/docs/html/training/load-data-background/setup-loader.jd b/docs/html/training/load-data-background/setup-loader.jd
index 4b40611..17fe7b0 100644
--- a/docs/html/training/load-data-background/setup-loader.jd
+++ b/docs/html/training/load-data-background/setup-loader.jd
@@ -1,4 +1,4 @@
-page.title=Setting Up the Loader
+page.title=Running a Query with a CursorLoader
trainingnavtop=true
startpage=true
@@ -10,81 +10,133 @@
<h2>This lesson teaches you to</h2>
<ol>
<li>
- <a href="#AddExtensions">Extend an Activity</a>
+ <a href="#Extend">Define an Activity That Uses CursorLoader</a>
</li>
<li>
- <a href="#GetLoader">Retrieve a LoaderManager</a>
+ <a href="#InitializeLoader">Initialize the Query</a>
</li>
<li>
- <a href="#InitializeLoader">Initialize the Loader Framework</a>
+ <a href="#DefineLaunch">Start the Query</a>
</li>
</ol>
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
</div>
</div>
<p>
- You create a {@link android.support.v4.content.CursorLoader} within a
- <b>loader framework</b>. To set up the framework, you implement the
+ A {@link android.support.v4.content.CursorLoader} runs an asynchronous query in the background
+ against a {@link android.content.ContentProvider}, and returns the results to the
+ {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity} from which it
+ was called. This allows the {@link android.app.Activity} or
+ {@link android.support.v4.app.FragmentActivity} to continue to interact with the user while the
+ query is ongoing.
+</p>
+<h2 id="Extend">Define an Activity That Uses CursorLoader</h2>
+<p>
+ To use a {@link android.support.v4.content.CursorLoader} with an
+ {@link android.app.Activity} or {@link android.support.v4.app.FragmentActivity}, use the
{@link android.support.v4.app.LoaderManager.LoaderCallbacks LoaderCallbacks<Cursor>}
- as part of an {@link android.app.Activity}. In addition, to provide compatibility
- compatible with platform versions starting with Android 1.6, you must extend the
- {@link android.app.Activity} with the {@link android.support.v4.app.FragmentActivity} class.
+ interface. A {@link android.support.v4.content.CursorLoader} invokes callbacks defined
+ in this interface to communicate with the class; this lesson and the next one
+ describe each callback in detail.
</p>
+<p>
+ For example, this is how you should define a {@link android.support.v4.app.FragmentActivity}
+ that uses the support library version of {@link android.support.v4.content.CursorLoader}. By
+ extending {@link android.support.v4.app.FragmentActivity}, you get support for
+ {@link android.support.v4.content.CursorLoader} as well as
+ {@link android.support.v4.app.Fragment}:
+</p>
+<pre>
+public class PhotoThumbnailFragment extends FragmentActivity implements
+ LoaderManager.LoaderCallbacks<Cursor> {
+...
+}
+</pre>
+<h2 id="InitializeLoader">Initialize the Query</h2>
+<p>
+ To initialize a query, call
+ {@link android.support.v4.app.LoaderManager#initLoader LoaderManager.initLoader()}. This
+ initializes the background framework. You can do this after the user has entered data that's
+ used in the query, or, if you don't need any user data, you can do it in
+ {@link android.support.v4.app.FragmentActivity#onCreate onCreate()} or
+ {@link android.support.v4.app.Fragment#onCreateView onCreateView()}. For example:
+</p>
+<pre>
+ // Identifies a particular Loader being used in this component
+ private static final int URL_LOADER = 0;
+ ...
+ /* When the system is ready for the Fragment to appear, this displays
+ * the Fragment's View
+ */
+ public View onCreateView(
+ LayoutInflater inflater,
+ ViewGroup viewGroup,
+ Bundle bundle) {
+ ...
+ /*
+ * Initializes the CursorLoader. The URL_LOADER value is eventually passed
+ * to onCreateLoader().
+ */
+ getLoaderManager().initLoader(URL_LOADER, null, this);
+ ...
+ }
+</pre>
<p class="note">
- <strong>Note:</strong> A {@link android.support.v4.app.Fragment} is not a prerequisite for
- {@link android.support.v4.content.CursorLoader}. As a convenience, the support library class
- {@link android.support.v4.app.FragmentActivity} contains the fragment and the loader frameworks,
- but they are completely independent of each other.
-</p>
-<p>
- Before you can use the loader framework, you need to initialize it. To do this, retrieve
- a {@link android.support.v4.app.LoaderManager} object and call its
- {@link android.support.v4.app.LoaderManager#initLoader initLoader()} method.
-</p>
-<p>
- If you do use one or more {@link android.support.v4.app.Fragment} objects in an
- {@link android.app.Activity}, the {@link android.support.v4.app.LoaderManager} you retrieve is
- available to all of them.
-</p>
-<h2 id="AddExtensions">Extend an Activity</h2>
-<p>
- To set up an {@link android.app.Activity} subclass to contain a
- {@link android.support.v4.content.CursorLoader}, extend the subclass with
- must extend {@link android.support.v4.app.FragmentActivity}, which provides the loader
- framework, and implement the {@link android.support.v4.app.LoaderManager.LoaderCallbacks
- LoaderCallbacks<Cursor>} interface, which specifies method signatures that the loader
- framework uses to interact with the {@link android.app.Activity}.
-</p>
-<p>
- For example:
-</p>
-<pre>
-public class DisplayActivity extends FragmentActivity
- implements LoaderManager.LoaderCallbacks<Cursor>
-</pre>
-<h2 id="GetLoader">Retrieve a LoaderManager</h2>
-<p>
- To get an instance {@link android.support.v4.app.LoaderManager} for use in your
- {@link android.app.Activity}, call
+ <strong>Note:</strong> The method {@link android.support.v4.app.Fragment#getLoaderManager
+ getLoaderManager()} is only available in the {@link android.support.v4.app.Fragment} class. To
+ get a {@link android.support.v4.app.LoaderManager} in a
+ {@link android.support.v4.app.FragmentActivity}, call
{@link android.support.v4.app.FragmentActivity#getSupportLoaderManager
- FragmentActivity.getSupportLoaderManager()} at the beginning of the
- {@link android.app.Activity#onCreate onCreate()} method. For example:
+ getSupportLoaderManager()}.
</p>
-<pre>
-private LoaderManager mLoaderManager;
-public void onCreate() {
-...
-mLoaderManager = this.getSupportLoaderManager();
-</pre>
-<h2 id="InitializeLoader">Initialize the Loader Framework</h2>
+<h2 id="DefineLaunch">Start the Query</h2>
<p>
- Once you have the {@link android.support.v4.app.LoaderManager} object, initialize
- it by calling {@link android.support.v4.app.LoaderManager#initLoader initLoader()}. For
- example:
+ As soon as the background framework is initialized, it calls your implementation of
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onCreateLoader onCreateLoader()}.
+ To start the query, return a {@link android.support.v4.content.CursorLoader} from this method.
+ You can instantiate an empty {@link android.support.v4.content.CursorLoader} and then use its
+ methods to define your query, or you can instantiate the object and define the query at the
+ same time:
</p>
<pre>
-// CursorLoader instance identifier
-public static final int URL_LOADER = 0;
-...
-// Initializes the CursorLoader
-getSupportLoaderManager().initLoader(URL_LOADER, null, this);
+/*
+* Callback that's invoked when the system has initialized the Loader and
+* is ready to start the query. This usually happens when initLoader() is
+* called. The loaderID argument contains the ID value passed to the
+* initLoader() call.
+*/
+@Override
+public Loader<Cursor> onCreateLoader(int loaderID, Bundle bundle)
+{
+ /*
+ * Takes action based on the ID of the Loader that's being created
+ */
+ switch (loaderID) {
+ case URL_LOADER:
+ // Returns a new CursorLoader
+ return new CursorLoader(
+ getActivity(), // Parent activity context
+ mDataUrl, // Table to query
+ mProjection, // Projection to return
+ null, // No selection clause
+ null, // No selection arguments
+ null // Default sort order
+ );
+ default:
+ // An invalid id was passed in
+ return null;
+ }
+}
</pre>
+<p>
+ Once the background framework has the object, it starts the query in the background. When the
+ query is done, the background framework calls
+ {@link android.support.v4.app.LoaderManager.LoaderCallbacks#onLoadFinished onLoadFinished()},
+ which is described in the next lesson.
+</p>
diff --git a/docs/html/training/multiple-threads/communicate-ui.jd b/docs/html/training/multiple-threads/communicate-ui.jd
new file mode 100644
index 0000000..d9977d3
--- /dev/null
+++ b/docs/html/training/multiple-threads/communicate-ui.jd
@@ -0,0 +1,263 @@
+page.title=Communicating with the UI Thread
+
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#Handler">Define a Handler on the UI Thread</a></li>
+ <li><a href="#MoveValues">Move Data from a Task to the UI Thread</a>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
+</ul>
+
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<p>
+ In the previous lesson you learned how to start a task on a thread managed by
+ {@link java.util.concurrent.ThreadPoolExecutor}. This final lesson shows you how to send data
+ from the task to objects running on the user interface (UI) thread. This feature allows your
+ tasks to do background work and then move the results to UI elements such as bitmaps.
+</p>
+<p>
+ Every app has its own special thread that runs UI objects such as {@link android.view.View}
+ objects; this thread is called the UI thread. Only objects running on the UI thread have access
+ to other objects on that thread. Because tasks that you run on a thread from a thread pool
+ <em>aren't</em> running on your UI thread, they don't have access to UI objects. To move data
+ from a background thread to the UI thread, use a {@link android.os.Handler} that's
+ running on the UI thread.
+</p>
+<h2 id="Handler">Define a Handler on the UI Thread</h2>
+<p>
+ {@link android.os.Handler} is part of the Android system's framework for managing threads. A
+ {@link android.os.Handler} object receives messages and runs code to handle the messages.
+ Normally, you create a {@link android.os.Handler} for a new thread, but you can
+ also create a {@link android.os.Handler} that's connected to an existing thread.
+ When you connect a {@link android.os.Handler} to your UI thread, the code that handles messages
+ runs on the UI thread.
+</p>
+<p>
+ Instantiate the {@link android.os.Handler} object in the constructor for the class that
+ creates your thread pools, and store the object in a global variable. Connect it to the UI
+ thread by instantiating it with the {@link android.os.Handler#Handler(Looper) Handler(Looper)}
+ constructor. This constructor uses a {@link android.os.Looper} object, which is another part of
+ the Android system's thread management framework. When you instantiate a
+ {@link android.os.Handler} based on a particular {@link android.os.Looper} instance, the
+ {@link android.os.Handler} runs on the same thread as the {@link android.os.Looper}.
+ For example:
+</p>
+<pre>
+private PhotoManager() {
+...
+ // Defines a Handler object that's attached to the UI thread
+ mHandler = new Handler(Looper.getMainLooper()) {
+ ...
+</pre>
+<p>
+ Inside the {@link android.os.Handler}, override the {@link android.os.Handler#handleMessage
+ handleMessage()} method. The Android system invokes this method when it receives a new message
+ for a thread it's managing; all of the {@link android.os.Handler} objects for a particular
+ thread receive the same message. For example:
+</p>
+<pre>
+ /*
+ * handleMessage() defines the operations to perform when
+ * the Handler receives a new Message to process.
+ */
+ @Override
+ public void handleMessage(Message inputMessage) {
+ // Gets the image task from the incoming Message object.
+ PhotoTask photoTask = (PhotoTask) inputMessage.obj;
+ ...
+ }
+ ...
+ }
+}
+The next section shows how to tell the {@link android.os.Handler} to move data.
+</pre>
+<h2 id="MoveValues">Move Data from a Task to the UI Thread</h2>
+<p>
+ To move data from a task object running on a background thread to an object on the UI thread,
+ start by storing references to the data and the UI object in the task object. Next, pass the
+ task object and a status code to the object that instantiated the {@link android.os.Handler}.
+ In this object, send a {@link android.os.Message} containing the status and the task object to
+ the {@link android.os.Handler}. Because {@link android.os.Handler} is running on the UI thread,
+ it can move the data to the UI object.
+
+<h3>Store data in the task object</h3>
+<p>
+ For example, here's a {@link java.lang.Runnable}, running on a background thread, that decodes a
+ {@link android.graphics.Bitmap} and stores it in its parent object <code>PhotoTask</code>.
+ The {@link java.lang.Runnable} also stores the status code <code>DECODE_STATE_COMPLETED</code>.
+</p>
+<pre>
+// A class that decodes photo files into Bitmaps
+class PhotoDecodeRunnable implements Runnable {
+ ...
+ PhotoDecodeRunnable(PhotoTask downloadTask) {
+ mPhotoTask = downloadTask;
+ }
+ ...
+ // Gets the downloaded byte array
+ byte[] imageBuffer = mPhotoTask.getByteBuffer();
+ ...
+ // Runs the code for this task
+ public void run() {
+ ...
+ // Tries to decode the image buffer
+ returnBitmap = BitmapFactory.decodeByteArray(
+ imageBuffer,
+ 0,
+ imageBuffer.length,
+ bitmapOptions
+ );
+ ...
+ // Sets the ImageView Bitmap
+ mPhotoTask.setImage(returnBitmap);
+ // Reports a status of "completed"
+ mPhotoTask.handleDecodeState(DECODE_STATE_COMPLETED);
+ ...
+ }
+ ...
+}
+...
+</pre>
+<p>
+ <code>PhotoTask</code> also contains a handle to the {@link android.widget.ImageView} that
+ displays the {@link android.graphics.Bitmap}. Even though references to
+ the {@link android.graphics.Bitmap} and {@link android.widget.ImageView} are in the same object,
+ you can't assign the {@link android.graphics.Bitmap} to the {@link android.widget.ImageView},
+ because you're not currently running on the UI thread.
+</p>
+<p>
+ Instead, the next step is to send this status to the <code>PhotoTask</code> object.
+</p>
+<h3>Send status up the object hierarchy</h3>
+<p>
+ <code>PhotoTask</code> is the next higher object in the hierarchy. It maintains references to
+ the decoded data and the {@link android.view.View} object that will show the data. It receives
+ a status code from <code>PhotoDecodeRunnable</code> and passes it along to the object that
+ maintains thread pools and instantiates {@link android.os.Handler}:
+</p>
+<pre>
+public class PhotoTask {
+ ...
+ // Gets a handle to the object that creates the thread pools
+ sPhotoManager = PhotoManager.getInstance();
+ ...
+ public void handleDecodeState(int state) {
+ int outState;
+ // Converts the decode state to the overall state.
+ switch(state) {
+ case PhotoDecodeRunnable.DECODE_STATE_COMPLETED:
+ outState = PhotoManager.TASK_COMPLETE;
+ break;
+ ...
+ }
+ ...
+ // Calls the generalized state method
+ handleState(outState);
+ }
+ ...
+ // Passes the state to PhotoManager
+ void handleState(int state) {
+ /*
+ * Passes a handle to this task and the
+ * current state to the class that created
+ * the thread pools
+ */
+ sPhotoManager.handleState(this, state);
+ }
+ ...
+}
+</pre>
+<h3>Move data to the UI</h3>
+<p>
+ From the <code>PhotoTask</code> object, the <code>PhotoManager</code> object receives a status
+ code and a handle to the <code>PhotoTask</code> object. Because the status is
+ <code>TASK_COMPLETE</code>, creates a {@link android.os.Message} containing the state and task
+ object and sends it to the {@link android.os.Handler}:
+</p>
+<pre>
+public class PhotoManager {
+ ...
+ // Handle status messages from tasks
+ public void handleState(PhotoTask photoTask, int state) {
+ switch (state) {
+ ...
+ // The task finished downloading and decoding the image
+ case TASK_COMPLETE:
+ /*
+ * Creates a message for the Handler
+ * with the state and the task object
+ */
+ Message completeMessage =
+ mHandler.obtainMessage(state, photoTask);
+ completeMessage.sendToTarget();
+ break;
+ ...
+ }
+ ...
+ }
+</pre>
+<p>
+ Finally, {@link android.os.Handler#handleMessage Handler.handleMessage()} checks the status
+ code for each incoming {@link android.os.Message}. If the status code is
+ <code>TASK_COMPLETE</code>, then the task is finished, and the <code>PhotoTask</code> object
+ in the {@link android.os.Message} contains both a {@link android.graphics.Bitmap} and an
+ {@link android.widget.ImageView}. Because
+ {@link android.os.Handler#handleMessage Handler.handleMessage()} is
+ running on the UI thread, it can safely move the {@link android.graphics.Bitmap} to the
+ {@link android.widget.ImageView}:
+</p>
+<pre>
+ private PhotoManager() {
+ ...
+ mHandler = new Handler(Looper.getMainLooper()) {
+ @Override
+ public void handleMessage(Message inputMessage) {
+ // Gets the task from the incoming Message object.
+ PhotoTask photoTask = (PhotoTask) inputMessage.obj;
+ // Gets the ImageView for this task
+ PhotoView localView = photoTask.getPhotoView();
+ ...
+ switch (inputMessage.what) {
+ ...
+ // The decoding is done
+ case TASK_COMPLETE:
+ /*
+ * Moves the Bitmap from the task
+ * to the View
+ */
+ localView.setImageBitmap(photoTask.getImage());
+ break;
+ ...
+ default:
+ /*
+ * Pass along other messages from the UI
+ */
+ super.handleMessage(inputMessage);
+ }
+ ...
+ }
+ ...
+ }
+ ...
+ }
+...
+}
+</pre>
diff --git a/docs/html/training/multiple-threads/create-threadpool.jd b/docs/html/training/multiple-threads/create-threadpool.jd
new file mode 100644
index 0000000..4a4ddb1
--- /dev/null
+++ b/docs/html/training/multiple-threads/create-threadpool.jd
@@ -0,0 +1,238 @@
+page.title=Creating a Manager for Multiple Threads
+
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#ClassStructure">Define the Thread Pool Class</a>
+ <li><a href="#PoolParameters">Determine the Thread Pool Parameters</a></li>
+ <li><a href="#ThreadPool">Create a Pool of Threads</a></li>
+</ol>
+
+<!-- other docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
+</ul>
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+
+</div>
+</div>
+
+<p>
+ The previous lesson showed how to define a task that executes on a
+ separate thread. If you only want to run the task once, this may be all you need. If you want
+ to run a task repeatedly on different sets of data, but you only need one execution running at a
+ time, an {@link android.app.IntentService} suits your needs. To automatically run tasks
+ as resources become available, or to allow multiple tasks to run at the same time (or both),
+ you need to provide a managed collection of threads. To do this, use an instance of
+ {@link java.util.concurrent.ThreadPoolExecutor}, which runs a task from a queue when a thread
+ in its pool becomes free. To run a task, all you have to do is add it to the queue.
+</p>
+<p>
+ A thread pool can run multiple parallel instances of a task, so you should ensure that your
+ code is thread-safe. Enclose variables that can be accessed by more than one thread in a
+ <code>synchronized</code> block. This approach will prevent one thread from reading the variable
+ while another is writing to it. Typically, this situation arises with static variables, but it
+ also occurs in any object that is only instantiated once. To learn more about this, read the
+ <a href="{@docRoot}http://developer.android.com/guide/components/processes-and-threads.html">
+ Processes and Threads</a> API guide.
+
+</p>
+<h2 id="ClassStructure">Define the Thread Pool Class</h2>
+<p>
+ Instantiate {@link java.util.concurrent.ThreadPoolExecutor} in its own class. Within this class,
+ do the following:
+</p>
+<dl>
+ <dt>
+ Use static variables for thread pools
+ </dt>
+ <dd>
+ You may only want a single instance of a thread pool for your app, in order to have a
+ single control point for restricted CPU or network resources. If you have different
+ {@link java.lang.Runnable} types, you may want to have a thread pool for each one, but each
+ of these can be a single instance. For example, you can add this as part of your
+ global field declarations:
+<pre>
+public class PhotoManager {
+ ...
+ static {
+ ...
+ // Creates a single static instance of PhotoManager
+ sInstance = new PhotoManager();
+ }
+ ...
+</pre>
+ </dd>
+ <dt>
+ Use a private constructor
+ </dt>
+ <dd>
+ Making the constructor private ensures that it is a singleton, which means that you don't
+ have to enclose accesses to the class in a <code>synchronized</code> block:
+<pre>
+public class PhotoManager {
+ ...
+ /**
+ * Constructs the work queues and thread pools used to download
+ * and decode images. Because the constructor is marked private,
+ * it's unavailable to other classes, even in the same package.
+ */
+ private PhotoManager() {
+ ...
+ }
+</pre>
+ </dd>
+ <dt>
+ Start your tasks by calling methods in the thread pool class.
+ </dt>
+ <dd>
+ Define a method in the thread pool class that adds a task to a thread pool's queue. For
+ example:
+<pre>
+public class PhotoManager {
+ ...
+ // Called by the PhotoView to get a photo
+ static public PhotoTask startDownload(
+ PhotoView imageView,
+ boolean cacheFlag) {
+ ...
+ // Adds a download task to the thread pool for execution
+ sInstance.
+ mDownloadThreadPool.
+ execute(downloadTask.getHTTPDownloadRunnable());
+ ...
+ }
+</pre>
+ </dd>
+ <dt>
+ Instantiate a {@link android.os.Handler} in the constructor and attach it to your app's
+ UI thread.
+ </dt>
+ <dd>
+ A {@link android.os.Handler} allows your app to safely call the methods of UI objects
+ such as {@link android.view.View} objects. Most UI objects may only be safely altered from
+ the UI thread. This approach is described in more detail in the lesson
+ <a href="communicate-ui.html">Communicate with the UI Thread</a>. For example:
+<pre>
+ private PhotoManager() {
+ ...
+ // Defines a Handler object that's attached to the UI thread
+ mHandler = new Handler(Looper.getMainLooper()) {
+ /*
+ * handleMessage() defines the operations to perform when
+ * the Handler receives a new Message to process.
+ */
+ @Override
+ public void handleMessage(Message inputMessage) {
+ ...
+ }
+ ...
+ }
+ }
+</pre>
+ </dd>
+</dl>
+<h2 id="PoolParameters">Determine the Thread Pool Parameters</h2>
+<p>
+ Once you have the overall class structure, you can start defining the thread pool. To
+ instantiate a {@link java.util.concurrent.ThreadPoolExecutor} object, you need the
+ following values:
+</p>
+<dl>
+ <dt>
+ Initial pool size and maximum pool size
+ </dt>
+ <dd>
+ The initial number of threads to allocate to the pool, and the maximum allowable number.
+ The number of threads you can have in a thread pool depends primarily on the number of cores
+ available for your device. This number is available from the system environment:
+<pre>
+public class PhotoManager {
+...
+ /*
+ * Gets the number of available cores
+ * (not always the same as the maximum number of cores)
+ */
+ private static int NUMBER_OF_CORES =
+ Runtime.getRuntime().availableProcessors();
+}
+</pre>
+ This number may not reflect the number of physical cores in the device; some devices have
+ CPUs that deactivate one or more cores depending on the system load. For these devices,
+ {@link java.lang.Runtime#availableProcessors availableProcessors()} returns the number of
+ <i>active</i> cores, which may be less than the total number of cores.
+ </dd>
+ <dt>
+ Keep alive time and time unit
+ </dt>
+ <dd>
+ The duration that a thread will remain idle before it shuts down. The duration is
+ interpreted by the time unit value, one of the constants defined in
+ {@link java.util.concurrent.TimeUnit}.
+ </dd>
+ <dt>
+ A queue of tasks
+ </dt>
+ <dd>
+ The incoming queue from which {@link java.util.concurrent.ThreadPoolExecutor} takes
+ {@link java.lang.Runnable} objects. To start code on a thread, a thread pool manager takes a
+ {@link java.lang.Runnable} object from a first-in, first-out queue and attaches it to the
+ thread. You provide this queue object when you create the thread pool, using any queue class
+ that implements the {@link java.util.concurrent.BlockingQueue} interface. To match the
+ requirements of your app, you can choose from the available queue implementations; to learn
+ more about them, see the class overview for {@link java.util.concurrent.ThreadPoolExecutor}.
+ This example uses the {@link java.util.concurrent.LinkedBlockingQueue} class:
+<pre>
+public class PhotoManager {
+ ...
+ private PhotoManager() {
+ ...
+ // A queue of Runnables
+ private final BlockingQueue<Runnable> mDecodeWorkQueue;
+ ...
+ // Instantiates the queue of Runnables as a LinkedBlockingQueue
+ mDecodeWorkQueue = new LinkedBlockingQueue<Runnable>();
+ ...
+ }
+ ...
+}
+</pre>
+ </dd>
+</dl>
+<h2 id="ThreadPool">Create a Pool of Threads</h2>
+<p>
+ To create a pool of threads, instantiate a thread pool manager by calling
+ {@link java.util.concurrent.ThreadPoolExecutor#ThreadPoolExecutor ThreadPoolExecutor()}.
+ This creates and manages a constrained group of threads. Because the initial pool size and
+ the maximum pool size are the same, {@link java.util.concurrent.ThreadPoolExecutor} creates
+ all of the thread objects when it is instantiated. For example:
+</p>
+<pre>
+ private PhotoManager() {
+ ...
+ // Sets the amount of time an idle thread waits before terminating
+ private static final int KEEP_ALIVE_TIME = 1;
+ // Sets the Time Unit to seconds
+ private static final TimeUnit KEEP_ALIVE_TIME_UNIT = TimeUnit.SECONDS;
+ // Creates a thread pool manager
+ mDecodeThreadPool = new ThreadPoolExecutor(
+ NUMBER_OF_CORES, // Initial pool size
+ NUMBER_OF_CORES, // Max pool size
+ KEEP_ALIVE_TIME,
+ KEEP_ALIVE_TIME_UNIT,
+ mDecodeWorkQueue);
+ }
+</pre>
diff --git a/docs/html/training/multiple-threads/define-runnable.jd b/docs/html/training/multiple-threads/define-runnable.jd
new file mode 100644
index 0000000..17640a9
--- /dev/null
+++ b/docs/html/training/multiple-threads/define-runnable.jd
@@ -0,0 +1,110 @@
+page.title=Specifying the Code to Run on a Thread
+
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#ExtendClass">Define a Class that Implements Runnable</a></li>
+ <li><a href="#RunMethod">Implement the run() Method</a>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
+</ul>
+
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+</div>
+
+</div>
+</div>
+
+<p>
+ This lesson shows you how to implement a {@link java.lang.Runnable} class, which runs the code
+ in its {@link java.lang.Runnable#run Runnable.run()} method on a separate thread. You can also
+ pass a {@link java.lang.Runnable} to another object that can then attach it to a thread and
+ run it. One or more {@link java.lang.Runnable} objects that perform a particular operation are
+ sometimes called a <i>task</i>.
+</p>
+<p>
+ {@link java.lang.Thread} and {@link java.lang.Runnable} are basic classes that, on their own,
+ have only limited power. Instead, they're the basis of powerful Android classes such as
+ {@link android.os.HandlerThread}, {@link android.os.AsyncTask}, and
+ {@link android.app.IntentService}. {@link java.lang.Thread} and {@link java.lang.Runnable} are
+ also the basis of the class {@link java.util.concurrent.ThreadPoolExecutor}. This class
+ automatically manages threads and task queues, and can even run multiple threads in parallel.
+</p>
+<h2 id="ExtendClass">Define a Class that Implements Runnable</h2>
+<p>
+ Implementing a class that implements {@link java.lang.Runnable} is straightforward. For example:
+</p>
+<pre>
+public class PhotoDecodeRunnable implements Runnable {
+ ...
+ @Override
+ public void run() {
+ /*
+ * Code you want to run on the thread goes here
+ */
+ ...
+ }
+ ...
+}
+</pre>
+<h2 id="RunMethod">Implement the run() Method</h2>
+<p>
+ In the class, the {@link java.lang.Runnable#run Runnable.run()} method contains the
+ code that's executed. Usually, anything is allowable in a {@link java.lang.Runnable}. Remember,
+ though, that the {@link java.lang.Runnable} won't be running on the UI thread, so it can't
+ directly modify UI objects such as {@link android.view.View} objects. To communicate with
+ the UI thread, you have to use the techniques described in the lesson
+ <a href="communicate-ui.html">Communicate with the UI Thread</a>.
+</p>
+<p>
+ At the beginning of the {@link java.lang.Runnable#run run()} method, set the thread to use
+ background priority by calling
+ {@link android.os.Process#setThreadPriority Process.setThreadPriority()} with
+ {@link android.os.Process#THREAD_PRIORITY_BACKGROUND}. This approach reduces
+ resource competition between the {@link java.lang.Runnable} object's thread and the UI
+ thread.
+</p>
+<p>
+ You should also store a reference to the {@link java.lang.Runnable} object's
+ {@link java.lang.Thread} in the {@link java.lang.Runnable} itself, by calling
+ {@link java.lang.Thread#currentThread() Thread.currentThread()}.
+</p>
+<p>
+ The following snippet shows how to set up the {@link java.lang.Runnable#run run()} method:
+</p>
+<pre>
+class PhotoDecodeRunnable implements Runnable {
+...
+ /*
+ * Defines the code to run for this task.
+ */
+ @Override
+ public void run() {
+ // Moves the current Thread into the background
+ android.os.Process.setThreadPriority(android.os.Process.THREAD_PRIORITY_BACKGROUND);
+ ...
+ /*
+ * Stores the current Thread in the the PhotoTask instance,
+ * so that the instance
+ * can interrupt the Thread.
+ */
+ mPhotoTask.setImageDecodeThread(Thread.currentThread());
+ ...
+ }
+...
+}
+</pre>
diff --git a/docs/html/training/multiple-threads/index.jd b/docs/html/training/multiple-threads/index.jd
new file mode 100644
index 0000000..3ea57c5
--- /dev/null
+++ b/docs/html/training/multiple-threads/index.jd
@@ -0,0 +1,83 @@
+page.title=Sending Operations to Multiple Threads
+
+trainingnavtop=true
+startpage=true
+
+
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- Required platform, tools, add-ons, devices, knowledge, etc. -->
+<h2>Dependencies and prerequisites</h2>
+<ul>
+ <li>Android 3.0 (API Level 11) or higher</li>
+ <li>
+ <a href="{@docRoot}training/load-data-background/index.html">
+ Loading Data in the Background</a> training class
+ </li>
+ <li>
+ <a href="{@docRoot}training/run-background-service/index.html">
+ Running in a Background Service</a> training class
+ </li>
+</ul>
+
+<!-- related docs (NOT javadocs) -->
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
+</ul>
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<p>
+ The speed and efficiency of a long-running, data-intensive operation often improves when you
+ split it into smaller operations running on multiple threads. On a device that has a CPU with
+ multiple processors (cores), the system can run the threads in parallel, rather than making each
+ sub-operation wait for a chance to run. For example, decoding multiple image files in order to
+ display them on a thumbnail screen runs substantially faster when you do each decode on a
+ separate thread.
+</p>
+<p>
+ This class shows you how to set up and use multiple threads in an Android app, using a
+ thread pool object. You'll also learn how to define code to run on a thread and how to
+ communicate between one of these threads and the UI thread.
+</p>
+<h2>Lessons</h2>
+<dl>
+ <dt>
+ <b><a href="define-runnable.html">Specifying the Code to Run on a Thread</a></b>
+ </dt>
+ <dd>
+ Learn how to write code to run on a separate {@link java.lang.Thread}, by
+ defining a class that implements the {@link java.lang.Runnable} interface.
+ </dd>
+ <dt>
+ <b><a href="create-threadpool.html">Creating a Manager for Multiple Threads</a></b>
+ </dt>
+ <dd>
+ Learn how to create an object that manages a pool of {@link java.lang.Thread} objects and
+ a queue of {@link java.lang.Runnable} objects. This object is called a
+ {@link java.util.concurrent.ThreadPoolExecutor}.
+ </dd>
+ <dt>
+ <b><a href="run-code.html">Running Code on a Thread Pool Thread</a></b>
+ </dt>
+ <dd>
+ Learn how to run a {@link java.lang.Runnable} on a thread from the thread pool.
+ </dd>
+ <dt>
+ <b><a href="communicate-ui.html">Communicating with the UI Thread</a></b>
+ </dt>
+ <dd>
+ Learn how to communicate from a thread in the thread pool to the UI thread.
+ </dd>
+</dl>
+
diff --git a/docs/html/training/multiple-threads/run-code.jd b/docs/html/training/multiple-threads/run-code.jd
new file mode 100644
index 0000000..a828828
--- /dev/null
+++ b/docs/html/training/multiple-threads/run-code.jd
@@ -0,0 +1,148 @@
+page.title=Running Code on a Thread Pool Thread
+
+trainingnavtop=true
+@jd:body
+
+<div id="tb-wrapper">
+<div id="tb">
+
+<!-- table of contents -->
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li><a href="#RunRunnable">Run a Runnable on a Thread in the Thread Pool</a></li>
+ <li><a href="#StopThread">Interrupt Running Code</a></li>
+</ol>
+
+<h2>You should also read</h2>
+<ul>
+ <li><a href="{@docRoot}guide/components/processes-and-threads.html">Processes and Threads</a></li>
+</ul>
+
+
+<h2>Try it out</h2>
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+
+<p>
+ The previous lesson showed you how to define a class that manages thread pools and the tasks
+ that run on them. This lesson shows you how to run a task on a thread pool. To do this,
+ you add the task to the pool's work queue. When a thread becomes available, the
+ {@link java.util.concurrent.ThreadPoolExecutor} takes a task from the queue and runs it on the
+ thread.
+</p>
+<p>
+ This lesson also shows you how to stop a task that's running. You might want to do this if a
+ task starts, but then discovers that its work isn't necessary. Rather than wasting processor
+ time, you can cancel the thread the task is running on. For example, if you are downloading
+ images from the network and using a cache, you probably want to stop a task if it detects that
+ an image is already present in the cache. Depending on how you write your app, you may not be
+ able to detect this before you start the download.
+</p>
+<h2 id="RunRunnable">Run a Task on a Thread in the Thread Pool</h2>
+<p>
+ To start a task object on a thread in a particular thread pool, pass the
+ {@link java.lang.Runnable} to {@link java.util.concurrent.ThreadPoolExecutor#execute
+ ThreadPoolExecutor.execute()}. This call adds the task to the thread pool's work queue. When an
+ idle thread becomes available, the manager takes the task that has been waiting the longest and
+ runs it on the thread:
+</p>
+<pre>
+public class PhotoManager {
+ public void handleState(PhotoTask photoTask, int state) {
+ switch (state) {
+ // The task finished downloading the image
+ case DOWNLOAD_COMPLETE:
+ // Decodes the image
+ mDecodeThreadPool.execute(
+ photoTask.getPhotoDecodeRunnable());
+ ...
+ }
+ ...
+ }
+ ...
+}
+</pre>
+<p>
+ When {@link java.util.concurrent.ThreadPoolExecutor} starts a {@link java.lang.Runnable} on a
+ thread, it automatically calls the object's {@link java.lang.Runnable#run run()} method.
+</p>
+<h2 id="StopThread">Interrupt Running Code</h2>
+<p>
+ To stop a task, you need to interrupt the task's thread. To prepare to do this, you need to
+ store a handle to the task's thread when you create the task. For example:
+</p>
+<pre>
+class PhotoDecodeRunnable implements Runnable {
+ // Defines the code to run for this task
+ public void run() {
+ /*
+ * Stores the current Thread in the
+ * object that contains PhotoDecodeRunnable
+ */
+ mPhotoTask.setImageDecodeThread(Thread.currentThread());
+ ...
+ }
+ ...
+}
+</pre>
+<p>
+ To interrupt a thread, call {@link java.lang.Thread#interrupt Thread.interrupt()}. Notice that
+ {@link java.lang.Thread} objects are controlled by the system, which can modify them outside of
+ your app's process. For this reason, you need to lock access on a thread before you
+ interrupt it, by placing the access in a <code>synchronized</code> block. For example:
+</p>
+<pre>
+public class PhotoManager {
+ public static void cancelAll() {
+ /*
+ * Creates an array of Runnables that's the same size as the
+ * thread pool work queue
+ */
+ Runnable[] runnableArray = new Runnable[mDecodeWorkQueue.size()];
+ // Populates the array with the Runnables in the queue
+ mDecodeWorkQueue.toArray(runnableArray);
+ // Stores the array length in order to iterate over the array
+ int len = runnableArray.length;
+ /*
+ * Iterates over the array of Runnables and interrupts each one's Thread.
+ */
+ synchronized (sInstance) {
+ // Iterates over the array of tasks
+ for (int runnableIndex = 0; runnableIndex < len; runnableIndex++) {
+ // Gets the current thread
+ Thread thread = runnableArray[taskArrayIndex].mThread;
+ // if the Thread exists, post an interrupt to it
+ if (null != thread) {
+ thread.interrupt();
+ }
+ }
+ }
+ }
+ ...
+}
+</pre>
+<p>
+ In most cases, {@link java.lang.Thread#interrupt Thread.interrupt()} stops the thread
+ immediately. However, it only stops threads that are waiting, and will not interrupt CPU or
+ network-intensive tasks. To avoid slowing down or locking up the system, you should test for
+ any pending interrupt requests before attempting an operation :
+</p>
+<pre>
+/*
+ * Before continuing, checks to see that the Thread hasn't
+ * been interrupted
+ */
+if (Thread.interrupted()) {
+ return;
+}
+...
+// Decodes a byte array into a Bitmap (CPU-intensive)
+BitmapFactory.decodeByteArray(
+ imageBuffer, 0, imageBuffer.length, bitmapOptions);
+...
+</pre>
diff --git a/docs/html/training/multiple-threads/threadsample.zip b/docs/html/training/multiple-threads/threadsample.zip
new file mode 100644
index 0000000..bdc3ccf
--- /dev/null
+++ b/docs/html/training/multiple-threads/threadsample.zip
Binary files differ
diff --git a/docs/html/training/run-background-service/create-service.jd b/docs/html/training/run-background-service/create-service.jd
new file mode 100644
index 0000000..5f4799c
--- /dev/null
+++ b/docs/html/training/run-background-service/create-service.jd
@@ -0,0 +1,131 @@
+page.title=Creating a Background Service
+trainingnavtop=true
+@jd:body
+<div id="tb-wrapper">
+<div id="tb">
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li>
+ <a href="#CreateClass">Create an IntentService</a>
+ </li>
+ <li>
+ <a href="#DefineManifest">Define the IntentService in the Manifest</a>
+ </li>
+</ol>
+<h2>You should also read</h2>
+<ul>
+ <li>
+<a href="{@docRoot}guide/components/services.html#ExtendingIntentService">Extending the IntentService Class</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
+ </li>
+</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<p>
+ The {@link android.app.IntentService} class provides a straightforward structure for running
+ an operation on a single background thread. This allows it to handle long-running operations
+ without affecting your user interface's responsiveness. Also, an
+ {@link android.app.IntentService} isn't affected by most user interface lifecycle events, so it
+ continues to run in circumstances that would shut down an {@link android.os.AsyncTask}
+</p>
+<p>
+ An {@link android.app.IntentService} has a few limitations:
+</p>
+<ul>
+ <li>
+ It can't interact directly with your user interface. To put its results in the UI, you
+ have to send them to an {@link android.app.Activity}.
+ </li>
+ <li>
+ Work requests run sequentially. If an operation is running in an
+ {@link android.app.IntentService}, and you send it another request, the request waits until
+ the first operation is finished.
+ </li>
+ <li>
+ An operation running on an {@link android.app.IntentService} can't be interrupted.
+ </li>
+</ul>
+<p>
+ However, in most cases an {@link android.app.IntentService} is the preferred way to simple
+ background operations.
+</p>
+<p>
+ This lesson shows you how to create your own subclass of {@link android.app.IntentService}.
+ The lesson also shows you how to create the required callback method
+ {@link android.app.IntentService#onHandleIntent onHandleIntent()}. Finally, the lesson describes
+ shows you how to define the {@link android.app.IntentService} in your manifest file.
+</p>
+<h2 id="CreateClass">Create an IntentService</h2>
+<p>
+ To create an {@link android.app.IntentService} component for your app, define a class that
+ extends {@link android.app.IntentService}, and within it, define a method that
+ overrides {@link android.app.IntentService#onHandleIntent onHandleIntent()}. For example:
+</p>
+<pre>
+public class RSSPullService extends IntentService {
+ @Override
+ protected void onHandleIntent(Intent workIntent) {
+ // Gets data from the incoming Intent
+ String dataString = workIntent.getDataString();
+ ...
+ // Do work here, based on the contents of dataString
+ ...
+ }
+}
+</pre>
+<p>
+ Notice that the other callbacks of a regular {@link android.app.Service} component, such as
+ {@link android.app.Service#onStartCommand onStartCommand()} are automatically invoked by
+ {@link android.app.IntentService}. In an {@link android.app.IntentService}, you should avoid
+ overriding these callbacks.
+</p>
+<h2 id="DefineManifest">Define the IntentService in the Manifest</h2>
+<p>
+ An {@link android.app.IntentService} also needs an entry in your application manifest.
+ Provide this entry as a
+ <code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>
+ element that's a child of the
+ <code><a href="{@docRoot}guide/topics/manifest/application-element.html">
+ <application></a></code> element:
+</p>
+<pre>
+ <application
+ android:icon="@drawable/icon"
+ android:label="@string/app_name">
+ ...
+ <!--
+ Because android:exported is set to "false",
+ the service is only available to this app.
+ -->
+ <service
+ android:name=".RSSPullService"
+ android:exported="false"/>
+ ...
+ <application/>
+</pre>
+<p>
+ The attribute <code>android:name</code> specifies the class name of the
+ {@link android.app.IntentService}.
+</p>
+<p>
+ Notice that the
+ <code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>
+ element doesn't contain an intent filter. The {@link android.app.Activity} that sends work
+ requests to the service uses an explicit {@link android.content.Intent}, so no filter is needed.
+ This also means that only components in the same app or other applications with the same user ID
+ can access the service.
+</p>
+<p>
+ Now that you have the basic {@link android.app.IntentService} class, you can send work requests
+ to it with {@link android.content.Intent} objects. The procedure for constructing these objects
+ and sending them to your {@link android.app.IntentService} is described in the next lesson.
+</p>
diff --git a/docs/html/training/run-background-service/index.jd b/docs/html/training/run-background-service/index.jd
new file mode 100644
index 0000000..173b87a
--- /dev/null
+++ b/docs/html/training/run-background-service/index.jd
@@ -0,0 +1,68 @@
+page.title=Running in a Background Service
+trainingnavtop=true
+startpage=true
+@jd:body
+<div id="tb-wrapper">
+<div id="tb">
+<h2>Dependencies and prerequisites</h2>
+<ul>
+ <li>Android 1.6 (API Level 4) or higher</li>
+</ul>
+<h2>You should also read</h2>
+<ul>
+ <li>
+<a href="{@docRoot}guide/components/services.html#ExtendingIntentService">Extending the IntentService Class</a>
+ </li>
+ <li>
+ <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
+ </li>
+</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<!-- ------------------------------------------------------------------------------------------- -->
+<!-- Introduction -->
+<!-- ------------------------------------------------------------------------------------------- -->
+<p>
+ Unless you specify otherwise, most of the operations you do in an app run in the foreground on
+ a special thread called the UI thread. This can cause problems, because long-running operations
+ will interfere with the responsiveness of your user interface. This annoys your users, and can
+ even cause system errors. To avoid this, the Android framework offers several classes that
+ help you off-load operations onto a separate thread running in the background. The most useful
+ of these is {@link android.app.IntentService}.
+</p>
+<p>
+ This class describes how to implement an {@link android.app.IntentService}, send it work
+ requests, and report its results to other components.
+</p>
+<h2>Lessons</h2>
+<dl>
+ <dt>
+ <b><a href="create-service.html">Creating a Background Service</a></b>
+ </dt>
+ <dd>
+ Learn how to create an {@link android.app.IntentService}.
+ </dd>
+ <dt>
+ <b><a href="send-request.html">Sending Work Requests to the Background Service</a></b>
+ </dt>
+ <dd>
+ Learn how to send work requests to an {@link android.app.IntentService}.
+ </dd>
+ <dt>
+ <b><a href="report-status.html">Reporting Work Status</a></b>
+ </dt>
+ <dd>
+ Learn how to use an {@link android.content.Intent} and a
+ {@link android.support.v4.content.LocalBroadcastManager} to communicate the status of a
+ work request from an {@link android.app.IntentService} to the
+ {@link android.app.Activity} that sent the request.
+ </dd>
+</dl>
+
diff --git a/docs/html/training/run-background-service/report-status.jd b/docs/html/training/run-background-service/report-status.jd
new file mode 100644
index 0000000..41121c1
--- /dev/null
+++ b/docs/html/training/run-background-service/report-status.jd
@@ -0,0 +1,199 @@
+page.title=Reporting Work Status
+trainingnavtop=true
+@jd:body
+<div id="tb-wrapper">
+<div id="tb">
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li>
+ <a href="#ReportStatus">Report Status From an IntentService</a>
+ </li>
+ <li>
+ <a href="#ReceiveStatus">Receive Status Broadcasts from an IntentService</a>
+ </li>
+</ol>
+<h2>You should also read</h2>
+<ul>
+ <li>
+ <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
+ </li>
+ <li>
+ The section <b>Broadcast receivers</b> in the
+ <a href="{@docRoot}guide/components/fundamentals.html#Components">Application Components</a>
+ API guide.
+ </li>
+</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<p>
+ This lesson shows you how to report the status of a work request run in a background service
+ to the component that sent the request. This allows you, for example, to report the status of
+ the request in an {@link android.app.Activity} object's UI. The recommended way to send and
+ receive status is to use a {@link android.support.v4.content.LocalBroadcastManager}, which
+ limits broadcast {@link android.content.Intent} objects to components in your own app.
+</p>
+<h2 id="ReportStatus">Report Status From an IntentService</h2>
+
+<p>
+ To send the status of a work request in an {@link android.app.IntentService} to other
+ components, first create an {@link android.content.Intent} that contains the status in its
+ extended data. As an option, you can add an action and data URI to this
+ {@link android.content.Intent}.
+</p>
+<p>
+ Next, send the {@link android.content.Intent} by calling
+ {@link android.support.v4.content.LocalBroadcastManager#sendBroadcast
+ LocalBroadcastManager.sendBroadcast()}. This sends the {@link android.content.Intent} to any
+ component in your application that has registered to receive it.
+ To get an instance of {@link android.support.v4.content.LocalBroadcastManager}, call
+ {@link android.support.v4.content.LocalBroadcastManager#getInstance getInstance()}.
+</p>
+<p>
+ For example:
+</p>
+<pre>
+public final class Constants {
+ ...
+ // Defines a custom Intent action
+ public static final String BROADCAST_ACTION =
+ "com.example.android.threadsample.BROADCAST";
+ ...
+ // Defines the key for the status "extra" in an Intent
+ public static final String EXTENDED_DATA_STATUS =
+ "com.example.android.threadsample.STATUS";
+ ...
+}
+public class RSSPullService extends IntentService {
+...
+ /*
+ * Creates a new Intent containing a Uri object
+ * BROADCAST_ACTION is a custom Intent action
+ */
+ Intent localIntent =
+ new Intent(Constants.BROADCAST_ACTION)
+ // Puts the status into the Intent
+ .putExtra(Constants.EXTENDED_DATA_STATUS, status);
+ // Broadcasts the Intent to receivers in this app.
+ LocalBroadcastManager.getInstance(this).sendBroadcast(localIntent);
+...
+}
+</pre>
+<p>
+ The next step is to handle the incoming broadcast {@link android.content.Intent} objects in
+ the component that sent the original work request.
+</p>
+<h2 id="ReceiveStatus">Receive Status Broadcasts from an IntentService</h2>
+<p>
+
+ To receive broadcast {@link android.content.Intent} objects, use a subclass of
+ {@link android.content.BroadcastReceiver}. In the subclass, implement the
+ {@link android.content.BroadcastReceiver#onReceive BroadcastReceiver.onReceive()} callback
+ method, which {@link android.support.v4.content.LocalBroadcastManager} invokes when it receives
+ an {@link android.content.Intent}. {@link android.support.v4.content.LocalBroadcastManager}
+ passes the incoming {@link android.content.Intent} to
+ {@link android.content.BroadcastReceiver#onReceive BroadcastReceiver.onReceive()}.
+</p>
+<p>
+ For example:
+</p>
+<pre>
+// Broadcast receiver for receiving status updates from the IntentService
+private class ResponseReceiver extends BroadcastReceiver
+{
+ // Prevents instantiation
+ private DownloadStateReceiver() {
+ }
+ // Called when the BroadcastReceiver gets an Intent it's registered to receive
+ @
+ public void onReceive(Context context, Intent intent) {
+...
+ /*
+ * Handle Intents here.
+ */
+...
+ }
+}
+</pre>
+<p>
+ Once you've defined the {@link android.content.BroadcastReceiver}, you can define filters
+ for it that match specific actions, categories, and data. To do this, create
+ an {@link android.content.IntentFilter}. This first snippet shows how to define the filter:
+</p>
+<pre>
+// Class that displays photos
+public class DisplayActivity extends FragmentActivity {
+ ...
+ public void onCreate(Bundle stateBundle) {
+ ...
+ super.onCreate(stateBundle);
+ ...
+ // The filter's action is BROADCAST_ACTION
+ IntentFilter mStatusIntentFilter = new IntentFilter(
+ Constants.BROADCAST_ACTION);
+
+ // Adds a data filter for the HTTP scheme
+ mStatusIntentFilter.addDataScheme("http");
+ ...
+</pre>
+<p>
+ To register the {@link android.content.BroadcastReceiver} and the
+ {@link android.content.IntentFilter} with the system, get an instance of
+ {@link android.support.v4.content.LocalBroadcastManager} and call its
+ {@link android.support.v4.content.LocalBroadcastManager#registerReceiver registerReceiver()}
+ method. This next snippet shows how to register the {@link android.content.BroadcastReceiver}
+ and its {@link android.content.IntentFilter}:
+</p>
+<pre>
+ // Instantiates a new DownloadStateReceiver
+ DownloadStateReceiver mDownloadStateReceiver =
+ new DownloadStateReceiver();
+ // Registers the DownloadStateReceiver and its intent filters
+ LocalBroadcastManager.getInstance(this).registerReceiver(
+ mDownloadStateReceiver,
+ mStatusIntentFilter);
+ ...
+</pre>
+<p>
+ A single {@link android.content.BroadcastReceiver} can handle more than one type of broadcast
+ {@link android.content.Intent} object, each with its own action. This feature allows you to
+ run different code for each action, without having to define a separate
+ {@link android.content.BroadcastReceiver} for each action. To define another
+ {@link android.content.IntentFilter} for the same
+ {@link android.content.BroadcastReceiver}, create the {@link android.content.IntentFilter} and
+ repeat the call to
+ {@link android.support.v4.content.LocalBroadcastManager#registerReceiver registerReceiver()}.
+ For example:
+</p>
+<pre>
+ /*
+ * Instantiates a new action filter.
+ * No data filter is needed.
+ */
+ statusIntentFilter = new IntentFilter(Constants.ACTION_ZOOM_IMAGE);
+ ...
+ // Registers the receiver with the new filter
+ LocalBroadcastManager.getInstance(getActivity()).registerReceiver(
+ mDownloadStateReceiver,
+ mIntentFilter);
+</pre>
+<p>
+ Sending an broadcast {@link android.content.Intent} doesn't start or resume an
+ {@link android.app.Activity}. The {@link android.content.BroadcastReceiver} for an
+ {@link android.app.Activity} receives and processes {@link android.content.Intent} objects even
+ when your app is in the background, but doesn't force your app to the foreground. If you
+ want to notify the user about an event that happened in the background while your app was not
+ visible, use a {@link android.app.Notification}. <i>Never</i> start an
+ {@link android.app.Activity} in response to an incoming broadcast
+ {@link android.content.Intent}.
+</p>
+<p>
+
+</p>
+
diff --git a/docs/html/training/run-background-service/send-request.jd b/docs/html/training/run-background-service/send-request.jd
new file mode 100644
index 0000000..5b1114d
--- /dev/null
+++ b/docs/html/training/run-background-service/send-request.jd
@@ -0,0 +1,82 @@
+page.title=Sending Work Requests to the Background Service
+trainingnavtop=true
+@jd:body
+<div id="tb-wrapper">
+<div id="tb">
+<h2>This lesson teaches you to</h2>
+<ol>
+ <li>
+<a href="#CreateRequest">Create and Send a Work Request to an IntentService</a>
+ </li>
+</ol>
+<h2>You should also read</h2>
+<ul>
+ <li>
+ <a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>
+ </li>
+</ul>
+<h2>Try it out</h2>
+
+<div class="download-box">
+ <a href="{@docRoot}shareables/training/ThreadSample.zip" class="button">Download the sample</a>
+ <p class="filename">ThreadSample.zip</p>
+</div>
+
+</div>
+</div>
+<p>
+ The previous lesson showed you how to create an {@link android.app.IntentService} class. This
+ lesson shows you how to trigger the {@link android.app.IntentService} to run an operation by
+ sending it an {@link android.content.Intent}. This {@link android.content.Intent} can
+ contain optionally contain data for the {@link android.app.IntentService} to process. You can
+ send an {@link android.content.Intent} to an {@link android.app.IntentService} from any point
+ in an {@link android.app.Activity} or {@link android.app.Fragment}
+</p>
+<h2 id="CreateRequest">Create and Send a Work Request to an IntentService</h2>
+<p>
+ To create a work request and send it to an {@link android.app.IntentService}, create an
+ explicit {@link android.content.Intent}, add work request data to it, and send it to
+ {@link android.app.IntentService} by calling
+ {@link android.content.Context#startService startService()}.
+</p>
+<p>
+ The next snippets demonstrate this:
+</p>
+<ol>
+ <li>
+ Create a new, explicit {@link android.content.Intent} for the
+ {@link android.app.IntentService} called <code>RSSPullService</code>.
+ <br>
+<pre>
+/*
+ * Creates a new Intent to start the RSSPullService
+ * IntentService. Passes a URI in the
+ * Intent's "data" field.
+ */
+mServiceIntent = new Intent(getActivity(), RSSPullService.class);
+mServiceIntent.setData(Uri.parse(dataUrl));
+</pre>
+ </li>
+ <li>
+ Call {@link android.content.Context#startService startService()}
+ <br>
+<pre>
+// Starts the IntentService
+getActivity().startService(mServiceIntent);
+</pre>
+</ol>
+<p>
+ Notice that you can send the work request from anywhere in an Activity or Fragment.
+ For example, if you need to get user input first, you can send the request from a callback
+ that responds to a button click or similar gesture.
+</p>
+<p>
+ Once you call {@link android.content.Context#startService startService()},
+ the {@link android.app.IntentService} does the work defined in its
+ {@link android.app.IntentService#onHandleIntent onHandleIntent()} method, and then stops itself.
+</p>
+<p>
+ The next step is to report the results of the work request back to the originating Activity
+ or Fragment. The next lesson shows you how to do this with a
+ {@link android.content.BroadcastReceiver}.
+</p>
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index ba9bbcf..9518046 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -192,7 +192,9 @@
</ul>
</li>
</ul>
- </li><!-- end getting started -->
+ </li><!-- end getting started -->
+
+
<li class="nav-section">
@@ -605,7 +607,7 @@
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/notify-user/index.html"
description=
- "How to display messages called notifications outside of
+ "How to display messages called notifications outside of
your application's UI."
>Notifying the User</a>
</div>
@@ -679,19 +681,19 @@
zh-CN-lang="支持各种屏幕尺寸"
ko-lang="다양한 화면 크기 지원"
ja-lang="さまざまな画面サイズのサポート"
- es-lang="Cómo admitir varios tamaños de pantalla"
+ es-lang="Cómo admitir varios tamaños de pantalla"
>Supporting Different Screen Sizes</a>
</li>
<li><a href="/training/multiscreen/screendensities.html"
zh-CN-lang="支持各种屏幕密度"
ja-lang="さまざまな画面密度のサポート"
- es-lang="Cómo admitir varias densidades de pantalla"
+ es-lang="Cómo admitir varias densidades de pantalla"
>Supporting Different Screen Densities</a>
</li>
<li><a href="/training/multiscreen/adaptui.html"
zh-CN-lang="实施自适应用户界面流程"
ja-lang="順応性のある UI フローの実装"
- es-lang="Cómo implementar interfaces de usuario adaptables"
+ es-lang="Cómo implementar interfaces de usuario adaptables"
>Implementing Adaptive UI Flows</a>
</li>
</ul>
@@ -799,7 +801,81 @@
</li>
<!-- End best UX and UI -->
+
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/best-user-input.html">
+ <span class="small">Best Practices for</span><br/>
+ User Input
+ </a>
+ </div>
+ <ul>
+
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/gestures/index.html"
+ description=
+ "How to write apps that allow users to interact with the touch screen via touch gestures."
+ >Using Touch Gestures</a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/gestures/detector.html">
+ Detecting Common Gestures
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/gestures/movement.html">
+ Tracking Movement
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/gestures/scroll.html">
+ Animating a Scroll Gesture
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/gestures/multi.html">
+ Handling Multi-Touch Gestures
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/gestures/scale.html">
+ Dragging and Scaling
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/gestures/viewgroup.html">
+ Managing Touch Events in a ViewGroup
+ </a>
+ </li>
+ </ul>
+ </li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/keyboard-input/index.html"
+ description=
+ "How to specify the appearance and behaviors of soft input methods (such
+ as on-screen keyboards) and how to optimize the experience with
+ hardware keyboards."
+ >Handling Keyboard Input</a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/keyboard-input/style.html">
+ Specifying the Input Method Type
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/keyboard-input/visibility.html">
+ Handling Input Method Visibility
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/keyboard-input/navigation.html">
+ Supporting Keyboard Navigation
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/keyboard-input/commands.html">
+ Handling Keyboard Actions
+ </a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li> <!-- end of User Input -->
<li class="nav-section">
<div class="nav-section-header">
@@ -846,6 +922,46 @@
</ul>
</li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/run-background-service/index.html"
+ description=
+ "How to improve UI performance and responsiveness by sending work to a
+ Service running in the background"
+ >Running in a Background Service</a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/run-background-service/create-service.html">
+ Creating a Background Service
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/run-background-service/send-request.html">
+ Sending Work Requests to the Background Service
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/run-background-service/report-status.html">
+ Reporting Work Status
+ </a>
+ </li>
+ </ul>
+ </li>
+
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/load-data-background/index.html"
+ description="How to use CursorLoader to query data without
+ affecting UI responsiveness."
+ >Loading Data in the Background</a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/load-data-background/setup-loader.html">
+ Running a Query with a CursorLoader</a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/load-data-background/handle-results.html">
+ Handling the Results</a>
+ </li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
@@ -862,29 +978,56 @@
<li><a href="/training/monitoring-device-state/battery-monitoring.html"
zh-CN-lang="监控电池电量和充电状态"
ja-lang="電池残量と充電状態の監視"
- es-lang="Cómo controlar el nivel de batería y el estado de carga"
+ es-lang="Cómo controlar el nivel de batería y el estado de carga"
>Monitoring the Battery Level and Charging State</a>
</li>
<li><a href="/training/monitoring-device-state/docking-monitoring.html"
zh-CN-lang="确定和监控基座对接状态和类型"
ja-lang="ホルダーの装着状態とタイプの特定と監視"
- es-lang="Cómo determinar y controlar el tipo de conector y el estado de la conexión"
+ es-lang="Cómo determinar y controlar el tipo de conector y el estado de la conexión"
>Determining and Monitoring the Docking State and Type</a>
</li>
<li><a href="/training/monitoring-device-state/connectivity-monitoring.html"
zh-CN-lang="确定和监控网络连接状态"
ja-lang="接続状態の特定と監視"
- es-lang="Cómo determinar y controlar el estado de la conectividad"
+ es-lang="Cómo determinar y controlar el estado de la conectividad"
>Determining and Monitoring the Connectivity Status</a>
</li>
<li><a href="/training/monitoring-device-state/manifest-receivers.html"
zh-CN-lang="根据需要操作广播接收器"
ja-lang="オンデマンドでのブロードキャスト レシーバ操作"
- es-lang="Cómo manipular los receptores de emisión bajo demanda"
+ es-lang="Cómo manipular los receptores de emisión bajo demanda"
>Manipulating Broadcast Receivers On Demand</a>
</li>
</ul>
</li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>training/multiple-threads/index.html"
+ description=
+ "How to improve the performance and scalability of long-running operations by
+ dispatching work to multiple threads.">
+ Sending Operations to Multiple Threads</a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>training/multiple-threads/define-runnable.html">
+ Specifying the Code to Run on a Thread
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/multiple-threads/create-threadpool.html">
+ Creating a Manager for Multiple Threads
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/multiple-threads/run-code.html">
+ Running Code on a Thread Pool Thread
+ </a>
+ </li>
+ <li><a href="<?cs var:toroot ?>training/multiple-threads/communicate-ui.html">
+ Communicating with the UI Thread
+ </a>
+ </li>
+ </ul>
+ </li>
<li>
<a href="<?cs var:toroot ?>training/articles/perf-anr.html"
@@ -1006,8 +1149,6 @@
</li>
</ul>
</li>
-
-
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/monetization/index.html"
@@ -1028,7 +1169,6 @@
<!-- End best Publishing -->
</ul><!-- nav -->
-
<script type="text/javascript">
<!--
buildToggleLists();
diff --git a/tools/aapt/Bundle.h b/tools/aapt/Bundle.h
index fde3bd6..5089b9d 100644
--- a/tools/aapt/Bundle.h
+++ b/tools/aapt/Bundle.h
@@ -38,6 +38,7 @@
kCommandRemove,
kCommandPackage,
kCommandCrunch,
+ kCommandSingleCrunch,
} Command;
/*
@@ -62,6 +63,7 @@
mVersionCode(NULL), mVersionName(NULL), mCustomPackage(NULL), mExtraPackages(NULL),
mMaxResVersion(NULL), mDebugMode(false), mNonConstantId(false), mProduct(NULL),
mUseCrunchCache(false), mErrorOnFailedInsert(false), mOutputTextSymbols(NULL),
+ mSingleCrunchInputFile(NULL), mSingleCrunchOutputFile(NULL),
mArgc(0), mArgv(NULL)
{}
~Bundle(void) {}
@@ -176,6 +178,10 @@
bool getUseCrunchCache() const { return mUseCrunchCache; }
const char* getOutputTextSymbols() const { return mOutputTextSymbols; }
void setOutputTextSymbols(const char* val) { mOutputTextSymbols = val; }
+ const char* getSingleCrunchInputFile() const { return mSingleCrunchInputFile; }
+ void setSingleCrunchInputFile(const char* val) { mSingleCrunchInputFile = val; }
+ const char* getSingleCrunchOutputFile() const { return mSingleCrunchOutputFile; }
+ void setSingleCrunchOutputFile(const char* val) { mSingleCrunchOutputFile = val; }
/*
* Set and get the file specification.
@@ -283,6 +289,8 @@
bool mUseCrunchCache;
bool mErrorOnFailedInsert;
const char* mOutputTextSymbols;
+ const char* mSingleCrunchInputFile;
+ const char* mSingleCrunchOutputFile;
/* file specification */
int mArgc;
diff --git a/tools/aapt/Command.cpp b/tools/aapt/Command.cpp
index 0a5e590..b98925b 100644
--- a/tools/aapt/Command.cpp
+++ b/tools/aapt/Command.cpp
@@ -7,6 +7,7 @@
#include "Bundle.h"
#include "ResourceFilter.h"
#include "ResourceTable.h"
+#include "Images.h"
#include "XMLNode.h"
#include <utils/Log.h>
@@ -1839,6 +1840,21 @@
return NO_ERROR;
}
+/*
+ * Do PNG Crunching on a single flag
+ * -i points to a single png file
+ * -o points to a single png output file
+ */
+int doSingleCrunch(Bundle* bundle)
+{
+ fprintf(stdout, "Crunching single PNG file: %s\n", bundle->getSingleCrunchInputFile());
+ fprintf(stdout, "\tOutput file: %s\n", bundle->getSingleCrunchOutputFile());
+
+ String8 input(bundle->getSingleCrunchInputFile());
+ String8 output(bundle->getSingleCrunchOutputFile());
+ return preProcessImageToCache(bundle, input, output);
+}
+
char CONSOLE_DATA[2925] = {
32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32, 32,
32, 32, 32, 32, 32, 32, 32, 95, 46, 32, 32, 32, 32, 32, 32, 32, 32, 32,
diff --git a/tools/aapt/Main.cpp b/tools/aapt/Main.cpp
index f398de0..32fecb2 100644
--- a/tools/aapt/Main.cpp
+++ b/tools/aapt/Main.cpp
@@ -85,7 +85,11 @@
" Add specified files to Zip-compatible archive.\n\n", gProgName);
fprintf(stderr,
" %s c[runch] [-v] -S resource-sources ... -C output-folder ...\n"
- " Do PNG preprocessing and store the results in output folder.\n\n", gProgName);
+ " Do PNG preprocessing on one or several resource folders\n"
+ " and store the results in the output folder.\n\n", gProgName);
+ fprintf(stderr,
+ " %s s[ingleCrunch] [-v] -i input-file -o outputfile\n"
+ " Do PNG preprocessing on a single file.\n\n", gProgName);
fprintf(stderr,
" %s v[ersion]\n"
" Print program version.\n\n", gProgName);
@@ -203,13 +207,14 @@
// printf(" %d: '%s'\n", i, bundle->getFileSpecEntry(i));
switch (bundle->getCommand()) {
- case kCommandVersion: return doVersion(bundle);
- case kCommandList: return doList(bundle);
- case kCommandDump: return doDump(bundle);
- case kCommandAdd: return doAdd(bundle);
- case kCommandRemove: return doRemove(bundle);
- case kCommandPackage: return doPackage(bundle);
- case kCommandCrunch: return doCrunch(bundle);
+ case kCommandVersion: return doVersion(bundle);
+ case kCommandList: return doList(bundle);
+ case kCommandDump: return doDump(bundle);
+ case kCommandAdd: return doAdd(bundle);
+ case kCommandRemove: return doRemove(bundle);
+ case kCommandPackage: return doPackage(bundle);
+ case kCommandCrunch: return doCrunch(bundle);
+ case kCommandSingleCrunch: return doSingleCrunch(bundle);
default:
fprintf(stderr, "%s: requested command not yet supported\n", gProgName);
return 1;
@@ -249,6 +254,8 @@
bundle.setCommand(kCommandPackage);
else if (argv[1][0] == 'c')
bundle.setCommand(kCommandCrunch);
+ else if (argv[1][0] == 's')
+ bundle.setCommand(kCommandSingleCrunch);
else {
fprintf(stderr, "ERROR: Unknown command '%s'\n", argv[1]);
wantUsage = true;
@@ -427,6 +434,28 @@
convertPath(argv[0]);
bundle.setCrunchedOutputDir(argv[0]);
break;
+ case 'i':
+ argc--;
+ argv++;
+ if (!argc) {
+ fprintf(stderr, "ERROR: No argument supplied for '-i' option\n");
+ wantUsage = true;
+ goto bail;
+ }
+ convertPath(argv[0]);
+ bundle.setSingleCrunchInputFile(argv[0]);
+ break;
+ case 'o':
+ argc--;
+ argv++;
+ if (!argc) {
+ fprintf(stderr, "ERROR: No argument supplied for '-o' option\n");
+ wantUsage = true;
+ goto bail;
+ }
+ convertPath(argv[0]);
+ bundle.setSingleCrunchOutputFile(argv[0]);
+ break;
case '0':
argc--;
argv++;
diff --git a/tools/aapt/Main.h b/tools/aapt/Main.h
index d20c601..a6b39ac 100644
--- a/tools/aapt/Main.h
+++ b/tools/aapt/Main.h
@@ -29,6 +29,7 @@
extern int doRemove(Bundle* bundle);
extern int doPackage(Bundle* bundle);
extern int doCrunch(Bundle* bundle);
+extern int doSingleCrunch(Bundle* bundle);
extern int calcPercent(long uncompressedLen, long compressedLen);
